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Programmers’ Tools for Borland C/C++ 3.1, Microsoft C++ 7.0 and Borland Pascal 7.0 
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Add Professional Graphics to Your Windows Application 

This comprehensive library of functions lets you create a wide variety of chart types including: line plots, 
area plots, horizontal and vertical bar graphs (with 3D bar options), floating bars, scatter plots, group 
plots, high-low-close plots, and pie charts (with 3D pie chart options). You can combine multiple chart 
types in the same graph. Built-in dialog boxes let you edit chart characteristics such as: graph position, 
axes parameters, fonts, and data. Once you have created the charts, you can output them to Windows- 
supported printers at the resolution of the output device, producing presentation-quality charts. 


Royalty Free 

There are no royalties or runtime fees charged when you redistribute 
Windows applications that you have created using these tools. 


Now you can get our 
datasheets by FAX- 
call 617-449-1628 with your 
FAX machine and request 
document #05050. 


Pricing 

Standard Package includes the Windows Charting Tools DLL, support files, a 300 page manual and 20 
example programs. Please specify compiler (C or Pascal) when ordering - $400. 

The DLL Source Code (requires support files found in the Standard Package) for the Windows Charting Tools 
DLL is written in C and is available for an additional $400. 

Mastercard, Visa accepted. Shipping charge is $6 within USA, $10 Canada and $32 elsewhere. 


Call or Write for Demo Disk 
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Are you 
avoiding 
version 
control? 

Version control isn't just for teams! 

If you've ever accidentally deleted 
source crucial to a project, or 
introduced a bug into working code, 
you know you need a version control 
system. Until now VCS’s have been 
expensive and notoriously difficult to 
maintain. Introducing Source Control 
finally, individual programmers can 
track incremental code changes, just 
like large companies do for their most 
important projects! 

Think of it as object-oriented 
version control. 

Source Control's "project orientation” 
will take full advantage of your object- 
oriented code by allowing you to share 
code among active projects. 

Developing for multiple platforms? 
Source Control is available now for DOS, 
Windows, NT, Macintosh, OS/2 and 
UNIX. All of these versions are 
transparent across a network so you 
can work with one integrated code base 
rather than managing time consuming, 
unnecessarily redundant systems. 

If you are part of a team... 

Source Control grows easily to meet the 
needs of team development. A single 
user can get started for less than $300 
(list price) and licenses are available in 
increments of five, ten and more. You 
can economically install Source Control 
on your server and get instant, 
project-wide status reports. Find out 
the who, what, where and when of each 
component as you speed your team to 
that final build deadline. 

Upgrade from PVCS! 

Make a quick transition from your 
current configuration management 
system with Source Control's PVCS 
conversion utility. Add Powerline's 
make utility. Source Make, and 
automatically update files without time 
consuming manual check-in/check-out 
procedures. Start on your way to a fully 
integrated configuration management 
system! 

Call for more information! 

Powerline Software is dedicated to 
providing a suite of compiler and 
platform independent developer’s tools, 
including Source Print+, for source code 
management and Source View, the 
run-time debugger for C and C++. 

SOURCE CONTROL 

SOURCE MAKE 


1-800-257-5773 
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From 

the Editor 


More than once, a reader has expressed some puzzlement at our attempts to keep magazine 
code compatible with Zortech C++, as well as Borland and Microsoft compilers. After all, no more than 
a few percent of our readers claim to use Zortech, so why bother? There are other fine C++ compilers, 
such as Watcom and Metaware, but the main products aimed at 16-bit, Windows, no-need-to-buy- 
an-SDK, C++ programming are Borland C++, Microsoft C++, and (in distant third place) Zortech C++. I 
believe having three rather than two strong contenders in this market would contribute to higher 
quality and lower prices for Windows C++ compilers. For example, I think we have competition to 
thank for the fact that after issuing the mediocre Microsoft C v6.0 (which inspired many programmers 
to move to Borland C++ or even back to Microsoft C v5.1), Microsoft got its act together and finally 
produced their first C++ compiler, followed by the highly successful Visual C++. 

I've used Zortech C++ from its very first version. I bought it because it was the first C++ compiler available 
for my PC that did not require a separate C compiler or more than 640Kb of memory. Until Borland C++ v3.1 
leapfrogged them, Zortech consistently led both Borland and Microsoft in implementing the latest C++ lan¬ 
guage specifications (despite what a review in the September BYTE stated, Microsoft has still not imple¬ 
mented templates). Zortech C++ also contains a pretty stable and effective code optimizer; benchmarking 
compilers is a black art, but my anecdotal experience is that Zortech has always been very competitive in 
terms of generated code speed, size, and reliability. 

So what has held Zortech back? Several problems, but two head the list First, Microsoft compatibility; if 
you want 16-bit Windows C++ market share, you have to take it from Microsoft and Borland — which means 
individual programmers have to be willing to move their existing code to your compiler. Zortech offered 
nowhere near the degree of Microsoft compatibility that Borland did. Second, Zortech has long suffered from 
inadequate tech support, especially in comparison to Borland and Microsoft, who offer CompuServe support 
that typically gets questions answered (and they deal with large volumes) within 24 hours. 

Now Zortech C++ is new, improved, and renamed as the just-released Symantec C++ V6.0. I have just 
started to use the final beta of the product, but I am starting to think it might be a success, and here's why: 
First, Symantec did some intelligent outsourcing. They dumped the homegrown Zortech linker in favor of 
bundling OPTLINK v4.0. They bundled a new GUI development tool from Blue Sky, along with Microsoft's 
Foundation Class Library C++ classes (probably an indication that Microsoft is betting Symantec won't be 
much competition). Second, they have invested some energy in increasing Microsoft compatibility. I see that 
niggling little Microsoft functions like _getdcwd() and fnsplit() are now finally supplied. More critically, 
Symantec C++ now has a real inline assembler (it can even handle Pentium instructions). It seems likely that 
it will now take me less time to port Microsoft and Borland Windows programs to Symantec C++. 

Symantec C++ has many other features, including the ability to create Win32s applications. You will 
probably hear the most about its flashy, integrated environment for development and debugging. That’s a 
great plus, but it won't be enough. Symantec needs aggressive pricing aimed at getting Borland and Microsoft 
programmers to give the new compiler a try. Symantec needs to make tech support a priority; the company 
managed to rapidly alienate a good percentage of Actor programmers via their tech support channel —they 
can't afford that mistake here. They also need to jump on any language bugs that emerge; compiler reputa¬ 
tions spread fairly quickly in the C++ programming community, and the new compiler name is an opportunity 
for a new reputation. Finally, Symantec must court the third-party programming tools vendors, so that ads 
start reading "Supports Microsoft, Borland and Symantec." As a programmer, it's not in my best interests for 
any of these vendors to win the compiler war. Instead, I'm rooting for a continuation of the fierce competi¬ 
tion that has brought us the current crop of high-quality compilers at very reasonable prices. 


Ron Burk 

Editor 

CIS: 70302,2566 ; BIX: rlburk\ Internet: ronb@rdpub.com ("...!uunet!rdpub!ronb") 
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Develop 

Windows Applications 
Quickly and Easily 


Phase3 Has Everything You Need 


Visual Development 

The Phase3 visual development environment 
provides a comprehensive suite of tools for 
screen creation. All standard Windows 
screen objects - push buttons, radio buttons, 
dialog boxes, etc. - are selectable from icon 
bars and are dynamically placed and sized 
on the screen as appropriate for the 
application. Standard Windows APIs are 
available from list boxes and are supported 
with on-line documentation. 


Phase3 Database 

Phase3 includes a relationally complete 
database supplied as a Windows DLL. The 
database supports complex data relation¬ 
ships and access and data manipulation by 
any language through a comprehensive 
suite of supplied database routines. 
Database integrity is enhanced with 
rollback recovery and transaction control. 
The Phase3 data dictionary simplifies data 
model definition and maintenance. 


Query and Reporting 

The Report Writer includes standard 
features like flexible headers, footers, free 
text, calculated fields, sort group sections 
and breaks, and subtotals. Reports can also 
include bitmaps of drawings and photo¬ 
graphic images. Queries are executed with 
the Database Browser which also allows 
data entry and manipulation. Railway 
diagrams assist in query creation, prompt¬ 
ing the user for appropriate selections and 
eliminating syntactical errors. 



Royalty-Free Applications 

Windows is a trademark of Microsoft Corporation. Turbo Pascal 
for Windows and Borland Pascal 7.0 are trademarks of Borland 
International, Inc. All other trademarks or service marks are 
recognized as the property of their respective owners. 


Lower CASE, E-R Modeling 

Phase3 automates logical data model design 
with Entity-Relationship modeling. After a 
user describes entity relationships graphi¬ 
cally and enters field descriptions, Phase3 
generates the physical database based on an 
analysis of the entity relationships. Phase3 
automatically includes foreign keys in 
appropriate tables and restructures the 
database as requirements change. Phase3 
suggests appropriate referential integrity 
constraints to be enforced at runtime. 


Hierarchy Chart 

Phase3 maintains a graphical map of an entire 
application. The Hierarchy Chart includes all 
windows, dialogs, reports, and code routines. 
To access the underlying C or Pascal source 
code, simply point-and-click on any node. 
Phase3 generated source is easily accessed 
and extended with user written routines. User 
code is preserved even if an application is 
regenerated. The Hierarchy Chart and E-R 
Diagram provide instant core documentation 
for an application. 


Help Generator 

The Phase3 Help Generator allows the easy 
creation of a complete Windows application 
help subsystem including context sensitive 
on-line help. The Help Generator includes its 
own text editor that gives complete control 
over the content, appearance, and branching 
logic through highlighted trigger text. Phase3 
generates a Windows compatible file with an 
“.HLP” extension that is then accessible 
from within the Phase3 created application. 
No other external tools are required. 


very impressive 


. a thoroughly remarkable product... 

Jeff Duntemann 

PC Techniques 


“I was very impressed with Phase3, and using it 
made me wish I had learned Windows programming 
with a tool like this. Now that I know what it has to 
offer, I’ll probably use it to build the frame for most 
of my programs.” 

L. John Ribar 

Windows Tech Journal 

AAA 

“Phase3 hides the complexity of Windows program¬ 
ming but still allows an experienced programmer to 
drill down and extend generated C or Pascal source 
code, providing ultimate control.” 

Randy Goodhew 

Computer Software Columnist 

AAA 

“Phase3 takes an intuitive, innovative approach to 
developing Windows applications, it’s a pleasure to 
work with and has greatly boosted our productivity. 
One of the most important issues for us is that their 
technical support is excellent.” 

Reuben Halevi 

ISoft D&M 

AAA 

“It’s easy to put together an application with Phase3 
- everything’s integrated. And the Phase3 database 
is terrific. It’s closer to true relational than anything 
we’ve found.” 

Michael Erickson 

Prism Business Solutions 


Order Now 

800 - 851-5650 

Or Call for Free Demo Disk 
Fax(805)641-9083 


CALL NOW FOR COMPETITIVE UPGRADE PRICING 
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CUSTOMIZE YOUR 
WINDOWS! 

For Experienced Programmers— 

GIVE WINDOWS YOUR OWN 
DISTINCTIVE LOOK. 
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Extend the Windows API with your 
own components 

Build replacements for standard 
controls 

Create controls that handle huge 
amounts of text 


Learn how to 

• create a toolbox class 

• create a custom dialog class 

• interface custom controls to 

the Dialog editor 


This book includes ali the code for a 
powerful set of ready-to-use custom 
controls. You can modify the code for 
your own design. 


WINDOWS 
CUSTOM 
CONTROLS 


William Smith 
Robert Ward 


Compiles under Microsoft C/C++, Quick 
C, and Borland C++ and has been 
tested under Windows 3.1 


r 



Technical 

Books 


Companion Disk for $29.95 

ORDER TODAY! 


Order: Book W99, Disk W99d, 
Book and Disk W99c 

913-841-1631 
FAX 913-841-2624 
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Graphics 


Visual Implementation: 
A Graphical, Reusable 
About Box 

Paul Bonneau 


Typically, the last components of a Windows application to be written are the 
installation program and the “About” dialog box. As a result, these two items usually 
receive the least amount of attention. This is unfortunate, since the install program is 
the first thing a new user sees, and the About box will be on the screen many times 
during the lifetime of the application. Even though both components are incidental 
to the application itself, if either looks unprofessional to the user, the result will be a 
lower overall perception of the application’s quality. 

Several vendors provide third-party installation kits that can generate slick-look¬ 
ing, high-quality installation programs. Most of these are driven by a high-level 
scripting language, which removes the need to code the setup program in C. This 
article supplies the other component: it presents the implementation of a graphical, 
reusable About box. In developing the implementation, my two main goals were to 
keep the interface as simple as possible and to present the user with a professional¬ 
looking About box. 

The About box has evolved into something of a standard in that many applica¬ 
tions display a core set of elements: the application's icon, the application’s name, a 

an indication of the amount of system resources avail¬ 
able. Many software vendors also use the About box 
to show "credits" for the team that produced the 
product. This can range from the amusing animated 
sequence in Microsoft Excel to a simple list of the 
names of the members of the development team. 


copyright string, and often, 


Borland C++ v3.1 
Microsoft C/C++ v7.0a 
Zortech C++ v3.1 
Visual C++ vl.O 


Paul Bonneau is a Software Design Engineer at a major software firm. He was a 
developer of HyperChem, a molecular modeling system marketed by Autodesk. 
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Figure 1 A full-featured About box 


Since one of my goals is to keep the programming inter¬ 
face to my About box simple, I decided to position each of the 
core elements on the About box during initialization, rather 
than use a static dialog template. Positioning the core ele¬ 
ments programmatically is more work, but has the advantage 
of not requiring you to supply a dialog resource. Using a dialog 
resource would mean either changing your application's exist¬ 
ing resource file or encapsulating the About box code in a DLL, 
which would add another file to be installed during setup. 
Automatic positioning also allows me to make each core ele¬ 
ment optional without adversely affecting the appearance of 
the About box. For example, if you don’t want to supply a 
credits screen, you just pass in a NULL pointer for that 
parameter and the code will automatically rearrange the 
dialog so that it no longer contains a “Credits" button. Figure 1 



Do you need WYSIWYG Text Processing 
for your WINDOWS Application? 


Just get the TX Text-Control and the 1C Image-Control DLLs 

for changing your DOS applications to high quality 
WINDOWS software with such features as 

- Multiple fonts 

- Paragraph formatting 

- Zooming 

- Integration of Images 

c 

.0 

c 

GET YOUR FREE DEMO TODAY! 

Call 203-561-9805 (USA or Canada) 

The Aristos Company, 957 Farmington Avenue 
West Hartford, CT 06107, Phone 203-561 -9805 
Fax 203-561 -9807, CompuServe 73020,2101 
Elsewhere <onta<t 
DBS GmbH, Fahrenheitstrasse 1 
2800 Bremen 33, Germany 
Phone+49421 / 2208-161 
Fax +49421/2208-273 
CompuServe 100013,115 
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shows a demonstration About box with all of the optional 
parameters present. 

Screen Resolution 

Two common problems arise when laying out controls on 
a parent window. The first is how to vary the sizes and posi¬ 
tions of the controls to accommodate various dialog fonts, and 
the second is how to maintain pleasing intercontrol spacing 
on devices of varying resolution. If you specify these 
parameters in terms of pixels, you get a window that looks 
cramped at high resolutions and ungainly at low resolutions. 

Windows addresses the first problem by using “dialog 
units." Windows defines these to be 1/4 the average width 
and 1/8 the average height of the current dialog's font. This 
way, or so the theory goes, if you change the dialog's font, 
the sizes and positions of the controls will scale by the width 
and height of an average character in the new font. But 
problems can still occur. For example, suppose that you design 
a dialog to display a string containing a lot of m’s and w’s in a 
monotype font, where the width of each character is the 
same as that of the average character. If you now switch to a 
variable pitch font, the m's and w's will become wider, and if 
there are enough of them, the width of the bounding box of 
the new string may grow significantly. In fact, the new string 
may no longer fit in its control. The same problem exists be¬ 
tween devices of different resolution. Different video display 
drivers use different physical fonts for the system font. View¬ 
ing the same dialog on different display devices will produce 
different results, and depending on the dialog, some of those 
results may look bad. When I lay out a dialog, I always leave 
extra white space at the end of the text to help ensure that it 
will still fit if a different font or display device is used. Since I 
decided to position the controls algorithmically, dialog units 
are not a concern. The code will use the actual length of the 
strings, not a number based on some multiple of average 
character widths. 

The problem with device resolution can best be illustrated 
with an example. On a low-resolution device, say a standard 
640x480 VGA, a pair of adjacent controls may be separated by 
four pixels. But on a high-resolution display, such as an SVGA 
running at 1600x1280, four pixels can appear so small that the 
gap between the controls may be hard to distinguish. This 
problem is normally addressed by dialog units, since the 
default font on a high-resolution display tends to be larger (in 
pixels) than that on a low-resolution display and the average 
character width is correspondingly greater. Thus if the four 
pixels in the low-resolution display equal two dialog units, two 
dialog units in the font of the high-resolution display might be 
eight pixels. But if you are not using dialog units, you need 
some other metric to maintain intercontrol spacing. Border 
units are the ideal choice. 

You won’t see "border units” discussed in the SDK, but in 
fact they are used inside USER (the Windows DLL that provides 
most of its user interface API). A border unit is nothing more 
than the number of pixels recommended by the display driver 
for a vertical border’s width and a horizontal border’s height. 
You can obtain these values by calling GetSystemMetrics(), 
using the constants SM_CXBORDER and SM_CYBORDER, respec¬ 
tively. On a low-resolution display, both numbers are typically 
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1, which means Windows will use a one-pixel thick vertical 
border and a one-pixel-thick horizontal border for windows. 
On a high-resolution display, these numbers will likely in¬ 
crease, since a one-pixel thick line may be unpleasingly thin. 

The code that positions the controls in my About box uses 
a grid of n horizontal border units by n vertical border units. 
By keeping controls one grid unit away from one another (I 
chose 4 for the value of n), the code maintains a pleasing 
intercontrol spacing across displays of different resolutions. 

The Programmatic Interface 

about.h (Listing 1) is the include file that defines the inter¬ 
face to the graphical, reusable About box code. It consists of a 
single prototype, FAbout (). FAbout () takes the following ar¬ 
guments: 

• instance handle — used to register 
and create the About box window. 

• window handle, usually the 
application's “main" window, which 
the About box disables and centers 
itself over. 

• icon handle — if not NULL-, FAbout() 
displays this icon in the upper left- 
hand corner of the About box. 

• application name — if not NULL-, F- 
About() displays the application 
name string to the right of the icon 
at the top of the About box. 

• font handle-, this is the font FAbout () 
uses to display application name (if 
NULL, FAbout () uses the system font). 

The last three FAbout () parameters 

provide the copyright string, credits 
string, and title text for the caption bar. 

Any can be NULL, although presenting a 
text-less caption bar might seem a little 
odd. If the copyright string is present, 

FAbout () displays it below the applica¬ 
tion name. The routine displays avail¬ 
able memory and “system resources" 
below the icon and copyright string. If 
you do not supply a credits string, F- 
About() centers a single “OK” pushbut¬ 
ton at the bottom of the About box. 

Otherwise, FAbout () displays “OK” and 
“Credits” pushbuttons side by side. The 
credits string is a single NULL- ter¬ 
minated string that uses the sequence 
“\r\n” to start a new line. FAbout () dis¬ 
plays the credits by scrolling them into 
view from the bottom of the About 
box, just like movie credits. 

The Implementation 

about.c (Listing 2) is the C code for 
the About box. The entry point, F- 
About(), is rather long, but most of this 
is grungy code for placing the About 
box controls. The first task is to register 
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Listing 1 about, h - Interface to graphical, 
reusable About box 


I***★*★★★***★★★**★*★★*★★★★★★★★★★********★*★★★**★******j 

/* about.h */ 

/* — About message box interface. */ 

JJ 

BOOL FAbout(HINSTANCE hins, HWND hwnd, HIC0N hicn, 

LPSTR IpszProd, HF0NT hfntProd, LPSTR IpszCopyright, 
LPSTR lpgrszCredits, LPSTR IpszTitle); 

/* End of File */ 


a class for the About box's popup window if one does not 
already exist This window is analogous to the popup window 
of a dialog box. Originally, I tried building a dialog box 
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Listing 2 about.c - Source code for graphical, reusable About box 

/★★★★★★★★a********************************************/ 

int dyText = 0; /* Text height. */ 

/* about.c */ 

WNDCLASS wcs; /* About window class. */ 

/* -- About message box. */ 

HWND hwndAbout; /* About window. */ 

!***************************************************** j 

RECT rectOwner, rectAbout; 

linclude <windows.h> 

int x, y, dx, dy; 

linclude <windowsx.h> 

int dxScreen, dyScreen; 

linclude <mmsystem.h> 

char szMem[20], szRes[20]; 

linclude <string.h> 

MSG msg; 

linclude "about.h" 

TEXTMETRIC txm; 

Idefine cidCredits 1000 /* Credits button id. */ 

/* Register a class for the main window if there */ 

#define cidProd 1001 /* Product name id. */ 

/* isn't one yet. */ 

#define cbdrGrid 4 /* Cell in border units. */ 

if (GetClassInfo(hins, szAboutClass, &wcs) == 0) 

Idefine clrCredit RGB(0xff, 0x00, 0x00) 

( 

#define dtimScroll 33 /* ms per scan line. */ 

wcs.style = 0; 

Idefine cpleAbout 48 /* size of palette. */ 

wcs.lpfnWndProc = LwAboutWndProc; 
wcs.cbClsExtra = 0; 

/* Round w up to the nearest multiple of dw. */ 

wcs.cbWndExtra = sizeof(HICON) + sizeof(LPSTR); 

Idefine WRoundllp(w, dw) \ 

wcs.hlnstance = hins; 

(C((w) + (dw) - 1) / (dw)) * (dw)) 

wcs.hlcon « NULL; 
wcs.hCursor = NULL; 

typedef struct 

wcs.hbrBackground = (HBRUSH)(COLOR WINDOW + I); 

( 

wcs.lpszMenuName * NULL; 

int x, y; /* Origin. */ 

wcs.lpszClassName = szAboutClass; 

int dx, dy; /* Size. */ 

if (!RegisterClass(&wcs)) 

WORD cid; /* Control ID. */ 

return FALSE; 

LPSTR lpsz; /* Title. */ 

} CTI; /* ConTrol Info. */ 

1 

if ((hdc = GetDC(NULL)) == NULL) 

typedef struct 
/ 

return FALSE; 

l 

/* Control info--must come first. */ 

/* Place items. Start with white space at edge. */ 

CTI ctiBmp, ctiProd, ctiCopy, ctiMemT, ctiMem, 

memset(&abm, 0, sizeof abm); 

ctiResT, ctiRes, ctiOk, ctiCred; 

dxGrid = cbdrGrid * GetSystemMetrics(SM CXBORDER); 

int dx, dy; /* Client area. */ 

dyGrid = cbdrGrid * GetSystemMetrics(SM CYBORDER); 

} ABM; /* About Box metrics. */ 

typedef struct 

abm.dx = dxGrid; 
abm.dy = dyGrid; 

( 

/* Place bitmap in upper left. */ 

WORD wVersion; 

abm.ctiBmp.x = abm.dx; 

WORD cple; 

abm.ctiBmp.y = abm.dy; 

PALETTEENTRY rgple[cpleAbout]; 

if (hicn != NULL) 

) ABL; /* About Box Palette. */ 

{ 

abm.ctiBmp.dx = 

char szAboutClass[] = “AboutBoxClass”; 

GetSystemMetrics(SM CXICON) + dxGrid; 

int dxGrid, dyGrid; /* Grid unit. */ 

abm.ctiBmp.dy = 

GetSystemMetrics(SM CYICON) + dyGrid; 

BOOL FCalcSzCti(HDC, CTI *, LPSTR); 

abm.dx +« abm.ctiBmp.dx; 

LRESULT CALLBACK export 

abm.dy += abm.ctiBmp.dy; 

LwAboutWndProc(HWND, UINT, WPARAM, LPARAM); 
void EnsureWidthAbm(ABM *, LPSTR, HDC); 

) 

BOOL FCreateCti(HWND, CTI *); 

/* Place product name beside bitmap. */ 

void InitAbl(ABL *); 

abm.ctiProd.x = abm.ctiBmp.x + abm.ctiBmp.dx; 

void Rol1 Credits(HWND); 

abm.ctiProd.y = abm.ctiBmp.y; 

void RotatePalette(HPALETTE, ABL *); 

if (IpszProd == NULL) 

IpszProd = /* For wsprintf() call. */ 

int 

else 

FAbout (HINSTANCE hins, HWND hwnd, HICON hicn, 

( 

LPSTR IpszProd, HFONT hfntProd, LPSTR IpszCopyright, 

LPSTR IpszCredits, LPSTR IpszTitle) 

HFONT hfntSav; 

j **********★★*★**★*★★★*★★***★★*★**★**★****★*********** j 

if (hfntProd != NULL) 

/* — Display an "About" message box. */ 

hfntSav = SelectObject(hdc, hfntProd); 

/* -- hins : Application's instance handle. */ 

if (FCalcSzCti(hdc, &abm.ctiProd, IpszProd)) 

/* -- hwnd : Owner window (optional). */ 

( 

/* -- hicn : Icon to display (optional). */ 

abm.dx * abm.ctiProd.x + abm.ctiProd.dx; 

/* -- IpszProd : Name of product (optional). */ 

abm.dy « max(abm.dy, abm.ctiProd.dy); 

/* — hfntProd : Product name font (optional). */ 

abm.ctiProd.cid « cidProd; 

/* — IpszCopyright : Copyright notice (optional). */ 

1 

/* — IpszCredits : Credit string (optional). */ 

SelectObject(hdc, hfntSav); 

/* -- Return false for failure. */ 

!*★★★**★*★*★★*★**★***★**★★*★★********★*★★★★★★★******★★ j 
( 

) 

/* Place copyright string below product name. */ 

ABM abm; /* Control info. */ 

abm.ctiCopy.x = abm.ctiProd.x; 

int icti; /* Control index. */ 

abm.ctiCopy.y = abm.ctiProd.y + abm.ctiProd.dy; 

HDC hdc; /* For text info. */ 

if (FCalcSzCti(hdc, &abm.ctiCopy, IpszCopyright)) 
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template and using DialogBoxIndirectO so that the Win¬ 
dows dialog manager would create the controls, but because 
of the way dialog box and control templates are defined with 
variable-length embedded strings, it actually turned out to be 
simpler to create the controls explicitly. 

FAboutf) uses GetClassInfo() to see if the About box 
class has been registered. If not, it calls RegisterClass() with 
a window class structure that declares window extra bytes to 
hold the icon handle and the credits string. FAboutf) next 


obtains a screen-based device context, which it will need later 
when determining the size of the text controls. Passing NULL 
to GetDCf) is a handy way to obtain such a device context 
(GetDC(NULL) returns a device context for the desktop). 

Even though a static control will display an icon instead of a 
text string if you create it with the SS_IC0N style, I decided 
against using one. It is conceivable that some applications may 
wish to display a bitmap or even a metafile in place of the icon. 
This way the About box's popup window is responsible for 


Listing 2 continued 

{ 

EnsureWidthAbm(&abm, abm.ctiResT.lpsz, hdc); 

int dyT; 

EnsureWidthAbm(&abm, abm.ctiRes.lpsz, hdc); 

if (abm.ctiCopy.dx > abm.ctiProd.dx) 

/* Make sure client area is wide enough to */ 

abm.dx = abm.ctiCopy.x + abm.ctiCopy.dx; 

/* display credits. */ 

if ((dyT = abm.ctiCopy.y + abm.ctiCopy.dy) > 

dxScreen = GetSystemMetrics(SM CXSCREEN); 

abm.dy) 

dyScreen = GetSystemMetrics(SM CYSCREEN); 

abm.dy = dyT; 

if (IpszCredits != NULL) 

/ 


\ 

RECT rectT; 

/* Format strings and make sure there is room to */ 

int dxT; 

/* show them. */ 


wsprintf(szMem, "%ld KB Free", GetFreeSpace(O) / 1024); 

rectT.left = rectT.bottom = rectT.top = 0; 

wsprintf(szRes, “%d%% Free", 

rectT.right = dxScreen; 

GetFreeSystemResources(GF$R SYSTEMRESOURCES)); 

if (DrawText(hdc, IpszCredits, -1, &rectT, 

abm.ctiMemT.lpsz = "Memory:"; 

DT CALCRECT | DT EXPANDTABS | DT NOPREFIX) != 

abm.ctiMem.lpsz = szMem; 

0 && 

abm.ctiResT.lpsz = "System Resources:"; 

(dxT = rectT.right - rectT.left) > abm.dx) 

abm.ctiRes.lpsz = szRes; 

abm.dx = dxT; 

EnsureWidthAbm(&abm, abm.ctiMemT.lpsz, hdc); 

I 

EnsureWidthAbm(&abm, abm.ctiMem.lpsz, hdc); 
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Listing 2 continued 


/* Place memory title and display. */ 

SetWindowWord(hwndAbout, 0, (WORD)hicn); 

SetWindowLong(hwndAbout, sizeof hicn. 

abm.ctiMemT.x = dxGrid; 

(LONG)1pszCredits); 

GetTextMetrics(hdc, &txm); 

dyText = WRoundUp(txm.tmHeight, dyGrid); 

/* Create controls. */ 

abm.ctiMemT.y = abm.dy + dyGrid; 

for (icti » 1; icti < 9; icti++) 

abm.ctiHemT.dx ■ (abm.dx - dxGrid) / 2; 

if (IFCreateCti(hwndAbout, (CTI *)&abm + icti)) 

abm.ctiMemT.dy = dyText + dyGrid; 

{ 

abm.ctiMem.x = abm.ctiMemT.x + abm.ctiMemT.dx; 

DestroyWindow(hwndAbout); 
return FALSE; 

abm.ctiMem.y » abm.ctiMemT.y; 

) 

abm.ctiMem.dx » abm.ctiMemT.dx; 
abm.ctiMem.dy = abm.ctiMemT.dy; 

if (abm.ctiProd.lpsz != NULL && hfntProd != NULL) 

/* Place resource title and display. */ 

SendDlgItemMessage(hwndAbout, cidProd, 

WM SETFONT, (WPARAM)hfntProd, FALSE); 

abm.ctiResT.x = abm.ctiMemT.x; 

abm.ctiResT.y = abm.ctiMemT.y + abm.ctiMemT.dy; 

ShowWindow(hwndAbout, SW SHOWNORMAL); 

abm.ctiResT.dx = abm.ctiMemT.dx; 

while (GetMessage(&msg, NULL, 0, 0) && 

abm.ctiResT.dy ■ abm.ctiMemT.dy; 

IsWindow(hwndAbout)) 

abm.ctiRes.x = abm.ctiMem.x; 

if (!IsDialogMessage(hwndAbout, &msg)) 

{ 

abm.ctiRes.y = abm.ctiResT.y; 

TranslateMessage(&msg); 

abm.ctiRes.dx « abm.ctiMem.dx; 

DispatchMessage(8.msg); 

abm.ctiRes.dy = abm.ctiResT.dy; 

} 

abm.dy = abm.ctiRes.y + abm.ctiRes.dy; 

return TRUE; 

ReleaseDC(NULL, hdc); 

) 

/* Place OK and Credits buttons at bottom. */ 

BOOL 

abm.ctiOk.dx = (abm.dx - dxGrid) / 2; 

FCalcSzCti(HDC hdc, CTI * pcti, LPSTR lpsz) 

abm.ctiOk.x = IpszCredits == NULL ? 

^ ***************************************************** ^ 

(abm.dx - abm.ctiOk.dx - dxGrid) / 2 : dxGrid; 

/* — Calculate the bounding box for a string. */ 

abm.ctiOk.y « abm.dy; 

^★★★★★★★★★★★★★★★★★**************★*★★★***★***★★**★★**★★j 

abm.ctiOk.dy = dyText * 3 / 2 + dyGrid; 

( 

abm.ctiOk.cid = IDOK; 

RECT rect; 

abm.ctiOk.lpsz = “&OK"; 

abm.dy = abm.ctiOk.y + abm.ctiOk.dy; 

rect.right = GetSystemMetrics(SM CXSCREEN) / 2; 

if (IpszCredits != NULL) 

rect.top = rect.left = rect.bottom = 0; 
if (DrawText(hdc, lpsz, -1, &rect, DT CALCRECT | 

( 

DT EXPANDTABS | DT NOPREFIX | DT WORDBREAK) == 0) 

abm.ctiCred.x = abm.ctiOk.x + abm.ctiOk.dx; 

return FALSE; // Give up. 

abm.ctiCred.y = abm.ctiOk.y; 
abm.ctiCred.dx * abm.ctiOk.dx; 

pcti->dx = dxGrid + 

abm.ctiCred.dy « abm.ctiOk.dy; 

WRoundUp(rect.right - rect.left, dxGrid); 

abm.ctiCred.cid = cidCredits; 

pcti->dy = dyGrid + 

abm.ctiCred.lpsz = "JCredits"; 

WRoundUp(rect.bottom - rect.top, dyGrid); 

1 

pcti->lpsz = lpsz; 

/* Center about window over owner. */ 

return TRUE; 

) 

rectAbout.left » rectAbout.top = 0; 
rectAbout.right * abm.dx; 

void 

rectAbout.bottom = abm.dy; 

EnsureWidthAbm(ABM * pabm, LPSTR lpsz, HDC hdc) 

AdjustWindowRectEx(&rectAbout, WS CAPTION | 

J*****************************************************J 

WS SYSMENU, FALSE, WS EX DLGMODALFRAME); 

/* — Ensure about box client area can fit two of */ 

dx ■ rectAbout.right - rectAbout.left; 

/* the given string, side by side. */ 

dy = rectAbout.bottom - rectAbout.top; 

j*****************************************************j 

if (hwnd == NULL) 

{ 

hwnd = GetDesktopWindow(); 

SIZE dpt; 

GetWindowRect(hwnd, &rectOwner); 

int dx; 

x * ((rectOwner.right + rectOwner.left) - dx) / 2; 
y = ((rectOwner.bottom + rectOwner.top) - dy) / 2; 

if (GetTextExtentPoint(hdc, lpsz, lstrlen(lpsz) , 

if (x < 0) 

(LPSIZE)&dpt) == 0) 

x = 0; 

return; 

else if (x + dx > dxScreen) 
x = dxScreen - dx; 

dx ■ 2 * WRoundUp(dpt.cx, dxGrid) + 3 * dxGrid; 

if (y < 0) 

if (dx > pabm->dx) 

y = 0 ; 

pabm->dx = dx; 

else if (y + dy > dyScreen) 

} 

y = dyScreen - dy; 

/* Create about window. */ 

BOOL 

FCreateCti(HWND hwnd, CTI * pcti) 

if ((hwndAbout = CreateWindowEx( 

!*****************************************************! 

WS EX DLGMODALFRAME, szAboutClass, IpszTitle, 

/* .. Create a control . */ 

WS POPUP I WS CAPTION | WS SYSMENU, X, y, dx, dy, 

/* — Return FALSE for failure. */ 

hwnd, NULL, hi ns, NULL)) == NULL) 

j ***************************************************** j 

return FALSE; 

{ 
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painting the icon, so you would only have to change the 
paint-handling code to accommodate different graphics ob¬ 
jects. Even though the icon does not possess its own window, 
for the sake of readability I will refer to it as a control. 

If the parameter for a particular control is not NULL, F- 
About() calculates its width, rounded up to the nearest grid 
line, and adds an extra grid unit for intercontrol whitespace. If 
the parameter is NULL, FAbout() leaves its width at zero. This 
makes placing successive controls relative to their predeces¬ 
sors easy. 

Listing 2 continued 


DWORD ulwStyle = WS_CHILD | WSVISIBLE; 

char * pszClass = "static"; 

if (pcti->cid == 0 && pcti->lpsz == NULL) 
return TRUE; 

if (pcti->cid == IDOK) 

( 

ulwStyle |= WS_TABSTOP | BS_DEFPUSHBUTTON; 
pszClass * "Button"; 

) 

else if (pcti->cid == cidCredits) 

{ 

ulwStyle |= WS_TABSTOP | BS_PUSHBUTTON; 
pszClass « "Button"; 

I 

return CreateWindow(pszClass, pcti->lpsz, ulwStyle, 
pcti->x, pcti->y, 

pcti->dx - dxGrid, pcti->dy - dyGrid, 

hwnd, (HMENU)pcti->cid, GetWindowInstance(hwnd), 

NULL) !- NULL; 

) 

LRESULT CALLBACK _export 

LwAboutWndProc(HWND hwnd, UINT wm, WPARAM wParam, 

LPARAM 1wParam) 

j *★★★★****★******★★**★*★★★★★★★*★★★*★★*★**★****★**★★*★* j 

/* -- About box main window procedure. */ 

y***************************************************** ^ 

{ 

HWND hwndOwner; 

switch (wm) 

( 

default: 

break; 

case WM_CREATE: 

I 

HMENU hmnu; 

if ((hwndOwner - GetWindow(hwnd, GW_0WNER)) != 
NULL) 

EnableWindow(hwndOwner, FALSE); 
hmnu = GetSystemMenu(hwnd, FALSE); 
DeleteMenu(hmnu, SC_TASKLIST, MF_BYCOMMAND); 
DeleteMenu(hmnu, SC_MAXIMIZE, MFJYCOMMAND); 

DeleteMenu(hmnu, SC_MINIMIZE, MFJYCOMMAND); 

DeleteMenu(hmnu, SC_SIZE, MFJYCOMMAND); 
DeleteMenu(hmnu, SC_RESTORE, MFJYCOMMAND); 
DeleteMenu(hmnu, 3, MFJYPOSITION); 
DeleteMenu(hmnu, 1, MFJYPOSITION); 

) 

break; 

case WMJLOSE: 

if ((hwndOwner = GetWindow(hwnd, GWJWNER)) ! = 
NULL) 

EnableWindow(hwndOwner, TRUE); 
break; 
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Excel. But if you want to browse and edit tables, the Grid is the 
one. 
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Listing 2 continued 


case WM ACTIVATE: 

DT W0RDBREAK | DT EXPANDTABS) == 0) 

if (wParam != 0) 

goto LCleanup; 

I 

LRESULT lw; 

/* Create a monochrome bitmap. */ 
dx = rectMem.right - rectMem.left; 

lw = DefWindowProc(hwnd, wm, wParam, lwParam); 

dy = rectMem.bottom - rectMem.top; 

SetFocus(GetDlgItem(hwnd, IDOK)); 

if ((hbmp = CreateCompatibleBitmap(hdcMem, dx, dy)) 

return lw; 

== NULL) 

) 

goto LCleanup; 

break; 

hbmpSav » SelectObject(hdcMem, hbmp); 

PatBlt(hdcMem, 0, 0, dx, dy, WHITENESS); 

case WM PAINT: 

DrawText(hdcMem, lpsz, -1, &rectMem, DT CENTER | 

< 

PAINTSTRUCT wps; 

DT_EXPANDTABS | DT_NOPREFIX | DT_WORDBREAK); 

if (GetDeviceCaps(hdc, RASTERCAPS) & RC PALETTE) 

BeginPaint(hwnd, &wps); 

( 

DrawIcon(wps.hdc, dxGrid, dyGrid, 

InitAbl(&abl); 

(HICON)GetWindowWord(hwnd, 0)); 

if ((hpal = CreatePa1ette((LPLOGPALETTE)&abl)) 

EndPaint(hwnd, &wps); 

) 

return 0; 

!= NULL) 

I 

SelectPalette(hdc, hpal, FALSE); 

RealizePalette(hdc); 

case WM COMMAND: 

) 

switch (wParam) 

/ 

) 

i 

default: 

if (hpal == NULL) 

break; 

SetTextColor(hdc, clrCredit); 

case IDOK: 

SetBkColor(hdc, 0x00000000); 

case IDCANCEL: 

PatBlt(hdc, 0, 0, rectClient.right, 

PostMessage(hwnd, WM CLOSE, 0, 0); 
return 0; 

rectClient.bottom, BLACKNESS); 

x = (rectClient.right - dx) / 2; 

case cidCredits: 

dyScroll = dy + rectClient.bottom; 

RollCredits(hwnd); 

yBottom = rectClient.bottom - 1; 

return 0; 

tim = timeGetTime(); 

} 

for (y = 0; y < dyScroll; y++) 

break; 

( 

} 

return DefWindowProc(hwnd, wm, wParam, lwParam); 

DWORD timT; 

MSG msg; 

} 

if (PeekMessage(&msg, hwnd, WM KEYDOWN, 

WM KEYDOWN, PM REMOVE) || 

void 

PeekMessage(&msg, hwnd, WM LBUTTONDOWN, 

RollCredits(HWND hwnd) 

WM LBUTTONDOWN, PM REMOVE)) 

/*****************************************************i 

/* — Scroll the credits just like in the movies. */ 

break; 

!***★★★*★★*★★**★*★★*★★*★★★*★**★**★*★***★★*★★★*★★★★***★j 

if (hpal != NULL) 

( 

HDC hdc = NULL; 

( 

SetTextColor(hdc, 

HDC hdcMem = NULL; 

PALETTEINDEX(y % cpleAbout)); 

HBITMAP hbmp = NULL; 

RotatePalette(hpal, &abl); 

HBITMAP hbmpSav = NULL; 

} 

HPALETTE hpal = NULL; 

ScrollDC(hdc, 0, -1, &rectClient, NULL, NULL, 

RECT rectClient, rectMem; 

NULL); 

LPSTR lpsz; 

if (y < dy) 

int dx, dy, dyScroll; 

BitBlt(hdc, x, yBottom, rectClient.right, 

int x, y, yBottom; 

1, hdcMem, 0, y, SRCCOPY); 

DWORD tim; 

while ((timT = timeGetTime()) - tim < 

ABL abl; 

dtimScrol 1) 

if ((hdc = GetDC(hwnd)) == NULL) 

» 

tim = timT; 

return; 

if ((hdcMem = CreateCompatibleDC(hdc)) «■ NULL) 

} 

InvalidateRect(hwnd, NULL, TRUE); 

goto LCleanup; 

LCleanup: 

if (hbmpSav != NULL) 

/* Make a bitmap big enough for the credits. */ 

SelectObject(hdcMem, hbmpSav); 

lpsz = (LPSTR)GetWindowLong(hwnd, sizeof(HBITMAP)); 

if (hbmp != NULL) 

GetClientRect(hwnd, &rectClient); 

DeleteObject(hbmp); 

rectMem = rectClient; 

if (hdcMem != NULL) 

if (DrawText(hdc, lpsz, -1, KrectMem, 

DeleteDC(hdcMem); 

DT CALCRECT | DT CENTER | DT NOPREFIX | 

if (hdc != NULL) 


ReleaseDC(hwnd, hdc); 
if (hpal != NULL) 
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The code uses the structure named CTI to store informa¬ 
tion about each control. The x and y fields contain the posi¬ 
tion of the upper right-hand corner of the control, while dx 
and dy contain its width and height. The cid field holds the 
control's ID, which will be passed via the hmenu parameter to 
CreateUindow(). The ID is important only for the two (possibly 
one) pushbuttons and the application name static text. A uni¬ 
que control ID is required for the pushbuttons so that the 
About box window procedure can tell which button was 
pushed. A unique control ID is also necessary for the applica¬ 
tion name static text window so that FAbout() can set its 
font. 

The last field in the CTI structure is a pointer to the 
control's text. If the About box were modeless, this could be a 
problem. In particular, the credits string 
must be valid throughout the lifetime of 
the About box. If it existed as an auto¬ 
matic variable in the caller’s stack 
frame, you would be in trouble, since a 
modeless FAbout() would return while 
the About box was on the screen, and 
if the caller returned, the credits string 
would become invalid. But since the 
About box is modal, FAbout () will not 
return until the About box has been 
dismissed. Thus any pointers to text 
residing on the stack will be valid 
throughout the About box's lifetime. 

The next structure, ABM, describes 
the entire About box. It has a CTI field 
for each of the controls, and a dx and 
dy field for the width and height of the 
About box's client area. As FAbout () 
calculates the position of each control, 
it fills out the control's CTI field and ad¬ 
justs the About box’s client area size. 

The code that determines the 
bounding rectangle for the application 
name and copyright strings uses the 
helper function FCalcSzCti(). This 
function in turn, uses the amazingly 
versatile DrawText() to do the actual 
work. FCalcSzCti() calls DrawText() 
with the DTJCALCRCCT and 
DTJIORDBREAK flags to calculate the 
dimensions of the bounding rectangle. 

The rectangle is initially set to half the 
width of the screen. If the text fits on a 
single line, DrawText() adjusts the right 
side to just contain the text. If the 
string is too long, DrawText() adjusts 
the bottom, based on the width, to 
enclose the string spread across multi¬ 
ple lines. 

FCalcSzCti () uses the DTJOPREFIX 
flag to prevent DrawText() from treat¬ 
ing a single ampersand preceding a text 
character as a signal to draw an under¬ 
line under the character (since that is 


Listing 2 continued 


DeleteObject(hpal); 

} 

void 

RotatePalette(HPALETTE hpal, ABL * pabl) 

^***************************************************** j 

/* — Rotate the palette entries up one. */ 

j*****************************************************j 

{ 

PALETTEENTRY pie; 

pie = pabl ->rgple[0]; 
memmove(pabl->rgple, pabl->rgple + 1, 
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Listing 2 continued 


(cpleAbout - 1) * sizeof pabl->rgple[0]); 
pabl->rgple[cpleAbout - 1] = pie; 
AnimatePalette(hpal, 0, cpleAbout, pabl->rgple); 

! 

void 

InitAbl(ABL * pabl) 

j*****************************************************I 

/* -- Initialize the palette with a "sawtooth". */ 

J*****************************************************j 
( 

int iple; 

int w = 0x7f - ((cpleAbout / 4) * 0x20); 

pabl->wVersion = 0x0300; 

pabl->cple = cpleAbout; 

for (iple = 0; iple < cpleAbout; iple++) 

{ 

BYTE b; 

w += iple < cpleAbout / 2 ? 0x20 : -0x20; 
b = w < 0 ? 0 : (w > Oxff ? Oxff : (BYTE)w); 
pabl->rgple[iple] .peRed = b; 
pabl->rgple[(iple + cpleAbout / 3) % 
cpleAbout].peGreen * b; 
pabl->rgple[(iple + 2 * cpleAbout / 3) % 
cpleAbout].peBlue = b; 
pabl->rgple[iple].peFlags * PC_RESERVED; 

) 

1 

/* End of File */ 
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the default behavior, DrawText() must have been created 
with dialog controls in mind). The DT_EXPANDTABS flag is used 
to make DrawText() expand a tab character to the next tab 
stop (the default tab stop is eight average character widths of 
the currently selected font; use the DT_TABST0P flag to over¬ 
ride this). If the application name font handle is not NULL, F- 
About() selects it into the device context before calling F- 
ColcSzCti (), since FCalcSzCti() uses the currently selected 
font. 

As Figure 1 shows, FAbout() displays two lines of resource 
information: the amount of available memory and the per¬ 
centage of free system resources. I chose to implement each 
line of resource information as a pair of controls, one for the 
title and one for the value text. This gives me control over the 
format of each resource line. The combination of the icon’s 
width and the maximum of the application name string width 
and copyright text width may be too narrow to accommodate 
the free system resources strings (especially if one or more of 
the elements is missing). To detect this situation and increase 
the width of the About box if necessary, FAbout () calls the 
helper function EnsureUidthAbm() for each string of the pair 
making up a resource line. The routine checks that two in¬ 
stances of the given string can fit side by side, resizing the 
About box's width, if necessary. This ensures that there is ade¬ 
quate room for both strings of the pair. 

This check is probably redundant if either the application 
name string or copyright string has forced the width of the 
About box to half the width of the screen, but is required if 
both the strings are small. The About box will normally not 
exceed half the width of the screen. It is theoretically possible 
that that width could be exceeded if the display driver sup¬ 
plies a very wide default system font. On a standard VGA, 
however, using the system font, there is plenty of space to fit 
both halves of each resource line within half the width of the 
screen. 

The next width check ensures that the About box client 
area is wide enough to display the widest line of the credits 
string (if the caller supplied one). If you supply a credits string 
with wide lines, the result can be a bizarre-looking About box, 
with lots of horizontal white space. You should try to keep 
each line in the credits string short, less than half the width of 
the screen if possible. 

FAbout() uses the API function GetFreeSpace() (available 
since Windows v3.0) to determine the amount of global 
memory remaining (this includes virtual memory). FAbout () 
calls GetFreeSystemResources () (only available since Win¬ 
dows V3.1) With the value GFSR_FREESYSTEMRESOURCES for the 
fuSysResource parameter to determine “free system resour¬ 
ces." This value is defined by Microsoft as the minimum of the 
ratio of maximum available memory versus allocated memory 
in each of the USER and GDI local heaps. 

After positioning the pushbuttons, FAbout() calls Adjust- 
UindowRectExf) to determine the size of the About box win¬ 
dow, including its non-client area. The code then attempts to 
center the About box over the owner window. If this would 
result in part of the About box being clipped by the screen, it 
moves the clipped edge back to abut the screen edge. F- 
About() then creates the popup window, and stores the icon 
handle and credits string in its extra class words. 
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The next section of code creates the controls. FAbout () 
calls the helper routine FCreateCti() from within a loop, 
iterating over the individual CTI members of the ABM struc¬ 
ture. The loop skips the first CTI, since this is for the icon, 
which does not possess a child window. FCreateCti() checks 
that the control ID and control text are not both NULL, which 
is the case when the corresponding parameter to FAbout() is 
NULL. Lastly, FCreateCtiO determines the class name string 
(''static" for text controls or "button” for the two buttons) and 
window styles, and calls CreateUindowf) to create the con¬ 
trol. 

If the font handle parameter is not NULL, FAbout() supplies 
it to the static control containing the application name via a 
m_SETFONT message. The last bit of code in this routine 
shows the About box window and enters a message loop that 
continues while the window exists. 

LwAboutNndProc () is the window procedure for the popup 
window. It disables its owner window (if it has one) at create 
time, and re-enables it just prior to termination of the About 
box, upon receipt of the NM_CLOSE message. Also at create 
time, LwAboutUndProc() trims extraneous menu items from 
the system menu, so that only “Move” and “Close” remain. 
This is consistent with dialogs that include a system menu 
and that are created by the Windows dialog manager. 
Without this trimming, the system menu would look like one 
found on a top-level window; it would contain items for "Re¬ 
store,” “Move,” “Size,” “Minimize,” “Maximize," a separator, 
“Close,” another separator, and "Switch To.” This is exactly 
what the system menu of a popup window (possessing a sys¬ 
tem menu) looks like when the Windows dialog manager first 
creates it. The dialog manager then removes items, using code 
very close to LwAboutWndProc()’s NM_CREATE handler. This 
conforms to Microsoft’s design guidelines described in The 
Windows Interface: An Application Design Guide, page 89. 

The HM_ACTIVATE case in LwAboutUndProcf) ensures the 
“OK” pushbutton has the focus when the About box is the 
active window. The UM_PAINT code is very simple - all it has 
to do is paint the icon, which it can take care of with a call to 
DrawIcon(). The next case handles UM_COMMAND messages. It 
handles notifications with a control ID of IDCANCEL, even 
though no cancel button exits, because IsDialogMessagef), 
called in the main loop, generates this notification when the 
user presses the Escape key. When LwAboutUndProcf) 
receives a notification with a control ID of either IDOK or ID- 
CANCEL, it calls DestroyUindowf) to terminate the About box. 
EndDialogO is useless in this case, since the default window 
procedure is DefUndProcf), not DefDlgProc(). Notifications 
with an ID of cidCredits are handled by the routine Roll- 
Credits (). 

Scrolling Color Credits 

1 got a little carried away with RollCredits(), but not too 
much, and the results are kind of spiffy, so perhaps it was 
worth it. RollCredits() detects if the display driver supports 
a palette. If not, the credits scroll onto the screen in whatever 
color the constant clrCredit is tdefine 'd to be (see the top 
of about.c - I picked red). RollCredits() first blacks out the 
client area, then scrolls the credits onto the client area from 
the bottom. If the adapter supports a palette, RollCredits() 
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= About Funky Test App 

Each line is terminated with \r\c 

Line 5 



Figure 2 Scrolling graphical credits in the About 
box 


uses palette animation to give the appearance of a rainbow of 
color scrolling through the already scrolling text. Figure 2 
shows a static snapshot of the scrolling credit window. 

Rather than draw the text on the window a line at a time, 
RollCredits() creates an offscreen monochrome bitmap 
large enough to hold the entire formatted credits text. I do 
this because the delay incurred when Windows draws the in¬ 
dividual lines of text produces a noticeable glitch as the 
credits scroll. Even if there are a lot of credits to display, the 
space required by the bitmap probably won't be a problem, 
since monochrome bitmaps are so much cheaper then color. 
An example may help illustrate the space required. On a very 
high-resolution display, say 1600x1280, with the About box at 
half the screen width, each line of the bitmap will occupy 800 
bits, or 100 bytes. Even if the credits bitmap is twice the 
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height of the screen (a very big development team) the bit¬ 
map would only require 200Kb. 

RollCredits() also relies on DrawText() to determine the 
size of the bounding rectangle for the text, which it then uses 
as the size for the bitmap. I used CreateCompatibleBitmapO 
to create the bitmap, even though the device context it is 
based on is a color memory device context, because Create¬ 
CompatibleBitmapO creates a bitmap compatible with the 
bitmap currently selected into the device context, which is 
always monochrome when a memory device context is first 
created. I could just as easily use CreateBitmapO , specifying 
1 for the number of planes and 1 for the bits per pixel. 

After RollCreditsO selects the bitmap into the memory 
device context, it wipes it clean using the WHITENESS raster 
operation code to PatBltf). DrawText() is called again, this 
time to actually draw the credit text into the bitmap. At this 
point RollCreditsO queries the palette capability of the 
device. If the device supports a palette, RollCreditsO initial¬ 
izes 48 palette colors with the helper routine InitAbl(), ob¬ 
tains a palette handle via CreatePaletteO, calls Select- 
Palette() to select the palette into the About window device 
context, and “realizes” the palette with a call to Realize- 
Palette(). 

RollCreditsO passes InitAblf) a pointer to a structure 
with type name ABL. This is simply the structure for a 48-color 
palette. The LOGPALLETTE type declared in windows.h contains 
a zero-length PALETTENTRY array. This works well when the 
LOGPALETTE is allocated and referenced through a pointer. But 
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since the palette I am using is fairly small, it is more con¬ 
venient to declare one on the stack, hence the ABL typedef. 

InitAbl() initializes the 48 PALETTENTRY elements com¬ 
prising the palette with three ramp, or sawtooth, waves, one 
for each color. The period of the wave is 48, and its amplitude 
ranges from -0x0101 to OxOlff. The green cycle leads the red 
by 16 entries, and blue leads green by 16. When the wave 
dips below zero, InitAbl() uses zero as the color value for 
red, green, or blue. When the wave rises above OxFF, OxFF is 
used. The result is that one color will remain full strength 
while the next ramps up. Once the “ramping up” color is at full 
strength, the first ramps back down to zero. The cycle then 
repeats with the next pair of colors. Its not rocket science, but 
it's not a bad “rainbow” for the amount of code involved. 

The initialized ABL can be passed directly to Create¬ 
PaletteO, which returns the handle to a logical palette. Un¬ 
like other GDI objects, a palette must not only be selected 
into a device context, but also “realized." Realization is the 
process of matching colors in the logical palette to entries in 
the physical palette. First, GDI allocates unused colors in the 
physical palette. Once these are exhausted, if there are still 
colors remaining to be matched, it maps these remaining logi¬ 
cal palette colors to the “closest color” in the physical palette. 
Since some or all of the colors in the logical palette have been 
remapped to other colors in the physical palette, the term 
“logical" is used to distinguish it from the physical palette. 

In practice, only display drivers that provide exactly 256 
colors support a palette. Lower resolution devices don't (there 
is no reason they shouldn’t —for example, the standard VGA 
driver could have been written to be a palettized driver), and 
higher resolution devices use explicit RGB values. 

Windows reserves 20 colors that correspond to the stand¬ 
ard 16 colors of a four-plane VGA, plus four others. Windows 
gives the palette associated with the foreground window the 
highest priority, and allows it to use the remaining 236 entries, 
even if they have been previously mapped by other logical 
palettes (in fact, up to 254 colors can be used with a call to 
the SetSystemPaletteUse0 function). Of course, an applica¬ 
tion using all 236 colors can make another background ap¬ 
plication using a palette look rather ugly. 

If the device does not support a palette, or if one could not 
be created for some reason (the likely culprit being low 
memory, in which case not much of anything will work), 
RollCreditsO sets the text color to the value of clrCredit. 
The background color is set to black, and the client area is 
erased to black. I am not bothering to save the previous back¬ 
ground and text colors, since Windows does not preserve the 
client area device context across calls to GetDCf) or Begin- 
Paint(), as would be the case had FAbout () registered the 
window class with one of the styles CSJOWNDC or CS_CLASSDC. 

RollCreditsO centers the credits bitmap horizontally in 
the About box's client area, and calculates the number of (ver¬ 
tical) pixels to scroll as the height of the credits bitmap plus 
the height of the About box’s client area. You can consider this 
the "distance" the top of the credit bitmap will “travel," since the 
credit display is terminated once the last pixel of the bottom¬ 
most string has scrolled off the top of the About box’s client area. 

Because some display adapters are faster than others 
(notably local bus video adapters, which scream in comparison 
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to standard adapters), the scrolling loop has a built-in time 
delay. I use timeGetTime() to determine the current time, 
measured in milliseconds, since Windows has started. The 
resolution of this API function is 1 millisecond, as opposed to 
the older API function GetTickCount() (or the equivalent Get- 
CurrentTimeO), which has a resolution of 55 milliseconds. I 
found that a delay of about 33 milliseconds between succes¬ 
sive one-pixel-high horizontal lines gave a pleasing scroll rate 
(30 lines per second), but you can tinker with the value of the 
constant dtimScroll to change the rate. 

In case the user doesn't really want to watch all the 
credits (the third or fourth time might start to get a bit 
tedious), the loop also polls for a HM_KEYDOWN or UM_LBUTT0N- 
DOIYN message. If it detects either, RollCredits() terminates 
the loop, and the key press or mouse click is eaten. It is 
necessary to eat the message, else a space or Enter key 
press would dismiss the About box. Since the About box has 
the focus (the user just pressed the credits pushbutton), Win¬ 
dows delivers all keyboard messages to the About box, but 
the user must click within the client area for a mouse click to 
stop the credits. You could change this behavior if you wish 
by first capturing the mouse, then releasing it at the end of 
the loop. This directs all mouse input to the About box’s client 
window, regardless of the mouse pointer location. 

If RollCredits() successfully created a logical palette, it 
sets the text color using the PALETTEINDEX macro. This macro 
returns a C0L0RREF that references a particular color index in 
the currently selected logical palette. I am using a value that 
cycles from 0 to 47, so that each successive one-pixel-high 


line copied from the credits bitmap will use whatever color 
the next entry in the palette possesses. The reason this works 
is that RollCredits() uses BitBlt() to transfer each line 
from the credits bitmap to the screen. When BitBltf) copies 
from a monochrome bitmap to a color device, it converts 1 
bits to the background color and 0 bits to the foreground 
color of the target device. 

After setting the text color, RollCredits() calls Rotate- 
Palette(). RotatePallete treats the PALETTEENTRY array in 
the ABL as a circular list, and rotates the contents forward by 
one palette entry. It then calls AnimatePalette (), which for¬ 
ces the entries of the physical palette that have been mapped 
to the currently realized palette to assume the color values 
supplied in the LOGPALETTE structure. An entry m-,ust have the 
PC_RESERVED bit set in its peFlags number to be placed in the 
physical palette. Since the device's physical palette is changed, 
the results appear immediately on the screen, without the 
need for repainting. The end result is that, since the palette 
has been rotated by one, each successive line of the credits 
bitmap copied to the About box's client area assumes the 
next color in the “rainbow.” 

Finally, once the last line of the credits bitmap has scrolled 
off the About box’s client area, RollCredits() invalidates the 
client area, so that the About box client area and controls will 
repaint themselves. The code disk contains the source code to 
testabou.exe, a small application to demonstrate the F- 
About() function (see the table of contents for information on 
obtaining the code disk directly or electronically). □ 
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Advanced Windows Programming 

Massimo Cesaro 


Martin Heller's Advanced Windows Programming is what I 
consider a “second-generation” Windows programming book: 
there is no coverage of Windows basics and the author as¬ 
sumes that the reader can successfully write and compile a 
Windows application using c language and the SDK. The object 
of the book is to demonstrate how to employ the Windows 
API in the development of real applications, that is, applica¬ 
tions that are intended for the market. As Windows 
developers soon discover, there is a world of difference be¬ 
tween planning the “Hello, Windows" application and tackling 
a medium-to-large software package. What is not written in 
the SDK manuals is how the programmer must think to 
develop real-world applications. 

Synopsis 

Chapter 1: Introduction. In chapter 1, the author first defines 
what he means by a real-world program (as opposed to a toy 
program), then shares his philosophy on Windows develop¬ 
ment (somewhat along the lines of “Small is beautiful,” with 
some amendments). He next turns to hard-core issues: 
memory management and memory use guidelines, interfacing 
with other programs either through Clipboard exchanges or 
the DDE and OLE protocols, and importing data by reading dif¬ 
ferent file formats. The section entitled “The Oral Tradition 
Codified” is a collection of practical tips on windows subclass¬ 
ing and superdassing, custom controls, multiple local heaps, 


exporting functions, the efficient structuring of a program, 
DPMI and WINMEM32.DLL issues, and other topics. The chapter 
ends with a suggested reading list that includes books and 
magazines on these subjects. 

Chapter 2: Some Fundamentals. Chapter 2 describes what 
Heller considers an adequate Windows development system, 
from the hardware list to the SDK components needed. The 
final section of the chapter is an introduction to debugging 
Windows programs. Heller describes how to set up a com¬ 
puter for effective debugging and how to set the various 
compilers’ switches and debugger options in order to compile 
and debug an application. 
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by Martin He/ler 
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Chapter 3: Displaying and Printing DIBs. As the “real” ap¬ 
plication to be developed in the book, Heller selected an 
image-editing program, a choice meant to highlight some of 
the troubles programmers encounter when developing ap¬ 
plications which require substantial amounts of system 
memory. The chapter opens with an explanation of the DIB 
bitmap format and an analysis of the SDK example program 
SHOWDIB, which is taken as a template for the final image¬ 
editing application. Using SHOWDIB as a starting point allows 
Heller to illustrate a concept he stresses in earlier chapters: try 
to reuse code — not only your own code, but other people’s 
code. He encourages you to take excerpts of code from other 
applications and modify them or add them to your own code 
(the Frankenstein Method), as he does here. 

The first modification Heller makes to SHOWDIB is to add 
the ability to read other bitmapped graphics file formats, such 
as GIF, PCX, TIFF, Targa, VICAR, and RAW. The source code for 
the handling of these formats was borrowed from well-known 
DOS and Windows public domain utilities, and Heller describes 
the process of adaptating the routines to Windows, the 
problems encountered, and the solutions adopted. 

He then adds some image-processing capabilities to the 
program, including conversion from RGB to gray-scale, adjust¬ 
ing colors (using various color representations such as RGB, 
HSV, and HLS), and playing with the Windows color palette. 
Since image-processing functions take a lot of execution time, 
the author gives, in passing, his solution to improving the 
cooperation between the program and Windows non-preemp- 
tive scheduler. In doing so, he illustrates some techniques for 


evaluating real vs. perceived performance using the profiling 
tools which come with the SDK. The chapter closes with a 
consideration of human interface design issues and with the 
source code for an “About” dialog box which, like that in Pro¬ 
gram Manager, gives useful statistics about the system’s 
resources. 

Chapter 4: Exploiting the Clipboard. Most Windows 
programmers sooner or later face the problem of transferring 
data to other applications. If the data format is limited to text 
only, then a few calls to the API can do the job, but if you 
must deal with more exotic formats, such as bitmapped 
graphics, then you are really on your own. Again, Heller 
provides code that will do almost everything needed to store 
and retrieve images to and from the clipboard. The author 
explains clearly how to handle clipboard data and points out 
the potential for bugs in an application with poor logical 
design. The section on cutting and pasting a region of an 
image on the clipboard includes a description on how the 
window procedure must deal with mouse messages (always a 
thorny issue) to implement region selection and dragging. As a 
finishing touch, Heller presents a clever way of merging palet¬ 
tes from different images that entails merging bitmaps and 
adding undo capabilities to the program. 

Chapter 5: Exploiting DDE and OLE. Starting with a definition 
of server and client, this chapter illustrates in a practical way 
how to implement DDE capabilities in a program. Heller discus¬ 
ses here the nine messages of the DDE protocol (known to 
many as the protocol from Hell) and the DDE management 
library (DDEML) introduced with Windows 3.1. Heller spends 
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significant time on the DDEML because this section introduces 
the section on OLE. He first compares DDEML and OLE, then 
explains OLE concepts and gives some pointers on how to 
design the OLE interface for an application. Heller presents 
code to read OLE objects from a file and shows how to 
manually update OLE links from a client application. The clos¬ 
ing section of the chapter is a critical analysis of when and 
why an application should be OLE- or DDE-aware. Heller's real- 
world experience and technical explanation make this analysis 
particularly useful, since this can be a commercial issue for 
the developer. 

Chapter 6: Debugging Windows Programs. In a perfect 
world there would be no need for a chapter on debugging, 
but since this is the “real-world’’ book, Heller summarizes the 
most common techniques for tracking and exterminating bugs 
in a Windows application. He covers the usual MessageBoxO 
probes with conditional messages, and the setup for a double¬ 
monitor system for debugging with CodeView for Windows 
and/or other Windows debuggers. Talking about testing the 
application with the debug kernel supplied with the SDK, 
Heller explains in detail how to use the debugging functions 
included in the API and how to use the TOOLHELP.DLL and the 
STRESS.DLL libraries. More conventional methods of debug¬ 
ging, such as writing messages to a file, the printer, or a win¬ 
dow are presented, and there are descriptions of debugging 
with CodeView, Multiscope, the Quick C integrated debugger, 
and the Borland, Zortech, and Watcom debuggers, as well as 
of the post-mortem debugging trace offered by Dr.Watson. 


All of the above is useful, but a real debug session ex¬ 
ample on the Image2 application is worth the cost of the 
book. The value here lies in the description of the method 
that the programmer can use to debug an event-driven ap¬ 
plication. Describing a debugger is easy, but describing how to 
use a debugger is not, and Heller's writing is a real knowledge 
transfer to the reader. The chapter closes with a description of 
common Windows program bugs, with the related causes, 
symptoms, and cures. 

Chapter 7-. Custom Edit Controls. This chapter actually dis¬ 
cusses how to subclass and superclass the edit control to 
achieve field validation. A quick review of the dialog box pro¬ 
cedure is followed by the implementation of validated date, 
float, decimal, and long fields by subclassing an edit control. 
Notes on how to change the font in controls and how the 
multiline edit control deals with the Clipboard close this chap¬ 
ter. 

Chapter 8: A Rich Text Edit Control. In this chapter “Rich" is 
Rich Text Format. After describing the history of Microsoft's 
own text format, Heller explains the data structures needed to 
represent Rich text. The reader learns how to use multiple 
fonts in an edit control, and how to implement text formatting 
(such as bold, italic, underlined, superscript, subscript, and 
rotated text) which Heller illustrates with working source code 
for a window that reads a RTF file and displays it. The chapter 
closes with a discussion of efficient scrolling and handling of 
large files. The final application, TESTPAR1, illustrates all the 
techniques described. 
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Chapter 9: Titling a Bitmap. The window procedure 
presented in the previous chapter is used to merge a RTF text 
with an image from the Image2 application. By cutting and 
pasting the earlier code to add text capabilities to the Image2 
application, Heller demonstrates that careful planning of an 
application allows the recycling of existing working code. 

Chapter 10: Porting. This chapter is for programmers who 
will port their code to another GUI, such as IBM OS/2 Presenta¬ 
tion Manager. (Heller mentions the Microsoft Windows Library 
for OS/2, but this product has now disappeared). Porting to 
DOS is easy with Magma MEWEL, but a few caveats exist and 
Heller warns the developer about them. The chapter closes 
with considerations on porting from DOS, Macintosh, and UNIX- 
X Window systems. 

Chapter IT. A Concluding Unscientific Postscript. The last 
chapter is a critical summary of the book. Heller writes about 
what he would like to have written (a major regret here is 
that Windows 3.1 was still in beta) and gives the reader some 
intriguing topics to reflect on. 

Appendix 1-. Exercise for the Student. The first appendix 
presents 12 programming exercises, varying from simple to 
advanced. Since some of them are really challenging, it would 
be nice if Heller would furnish the solutions in another book. 

Appendixes 2, 3, 4, 5: Using Zortech C++, Borland C++, Wat- 
com C, QuicK C. These appendixes discuss the differences be¬ 
tween different development tools, and how to cope with 
them. The discussions are interesting, but of limited usefulness 
because of the rapid obsolescence of specific version of these 
tools. 


Comments 

This is a book which should be near the developer's 
desktop, next to the cold pizza and Jolt Cola can. One feature I 
found particularly impressive is Heller’s willingness to acknow¬ 
ledge the work of other programmers. He notes that parts of 
the book illustrate techniques he learned from the Windows 
developers' community; wherever possible, credit is given to 
the original author of the original code. The book’s only weak 
point is that it was written when Windows 3.1 was still in 
beta and 3.0 was hot — that’s why real-mode concerns are 
addressed. The final commented source code for the examples 
is included in the companion diskettes, and while at $72.90 
the combination of book and disks is not cheap, the book will 
pay for itself in the next project you work on. Advanced Win¬ 
dows Programming is definitely worth reading for the profes¬ 
sional programmer, but even the amateur will find tricks and 
techniques that would require months of hacking with the 
SDK to discover. □ 
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Fax Image Encoding 

Robert L Hummel 




Facsimile technology was invented in 1843, predating the invention of the 
typewriter by over half a century and the introduction of the IBM PC by a staggering 
138 yearsl Nonetheless, it is only recently —and largely because of the availability of 
inexpensive fax modems — that fax has come to the attention of many PC program¬ 
mers. 

A standalone fax machine implements all phases of the fax session, from image 
preparation through the exchange of data over the communications channel through 
image reconstruction. When the session is conducted by a PC and a fax modem, 
however, the responsibilities for session management are partitioned between the 
two devices. The Electronic Industries Association (EIA) specifications for fax modems 
both define where this separation occurs and establish the details of the interface. 

The EIA defines a Class 1 fax modem in specification EIA/TIA-578. For a modem to 
be designated Class 1 means simply that it must provide the minimum services 
necessary to implement a Group 3 fax session using a standard command set. The 
PC is responsible for encoding the image (per the CCITT T.4 recommendation) and 
managing the document transmission session (per the CCITT T.30 recommendation). 

An EIA Class 2.0 fax modem contains a good deal more intelligence than a Class 1 
modem. The partitioning is adjusted so that much of the drudgery of implementing 
the T.30 protocols is offloaded from the PC to the modem. For both Class 1 and 2 
operations, however, the PC is responsible for preparing the image data for transmis¬ 
sion and interpreting the data on reception. 

As fax support becomes integrated into more applications, the odds are that 
sooner or later your may want to — or have to - generate or interpret fax-com¬ 
patible data. This article describes both the 1-dimensional and 2-dimensional fax 
encoding schemes used in Group 3 fax transmission and presents some observations 
on their programmatic implementation. 



Robert L Hummel is an electrical engineer, computer programmer, consultant, and 
commentator. He is the author of several popular programming books, including the 
new Ziff-Davis Press book Programmer's Technical Reference: Data and Fax Com¬ 
munications. Figures 2 and 3 are reprinted from that book and are copyright © 1993, 
Ziff-Davis Press, All Rights Reserved. 
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Figure 1 Group 3 one-dimensional encoding 
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The Fax image 

A fax machine converts a continuous image into a series of 
discrete scan lines. In turn, each scan line is composed of an 
identical number of individual pixels. A standard 8.5" x 11" 
page is scanned vertically to produce 1143 horizontal lines. 
Each horizontal line is composed of 1728 pixels. (If the image 
is scanned using the optional higher resolution mode, the ver¬ 


tical resolution is doubled; the horizon¬ 
tal resolution is unchanged.) 

At its simplest, the scanned data is a 
description of the placement of black 
and white pixels on a page. A single 
page, scanned at standard resolution, 
results in about 2 megabits of data. As¬ 
suming that the fax modem is operat¬ 
ing at 9600 bps, the raw data from a 
single page would require more than 
three minutes to transmit. 

But the typical fax image contains 
large expanses of the same color. A 
typewritten letter, for example, com¬ 
prises large area of white (the paper) 
with occasional areas of black (the char¬ 
acters). Line drawings are similarly 
proportioned. As a result, fax image 
data tends to be highly compressible 
via simple algorithms. 

One-Dimensional Encoding 

The CCITT T.4 standard describes a run-length encoding 
scheme that compresses the fax image data one scan line at 
a time. Each line of pixels is compressed individually according 
to a fixed set of rules. The encoding of one line has no de¬ 
pendency on previous lines. Because each scan line is inde¬ 
pendently encoded, an error that occurs in the communications 
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channel is not propagated throughout the document. This 
scheme is known as one-dimensional encoding. 

The 1728 pixels of a scan line are encoded using a series of 
codewords which can vary from 2 to 13 bits in length; each 
codeword represents a run of either all black or all white 
pixels. Within a single scan line, runs of white and black pixels 
alternate. 

To ensure that the colors produced by the receiving sys¬ 
tem remain in synchronization with the transmitter, all data 
lines must begin with a run of white pixels. If the first pixel in 
the line is black, a white run length of zero is encoded. Figure 
1 shows a single scan line in which the first step of encoding, 
dividing the line into runs of alternating colors, has been com¬ 
pleted. 

The second step of encoding is the translation of the run 
lengths into their corresponding codewords, single-color runs 
of 0 to 63 pixels are encoded using the terminating codewords 
shown in Table 1. The first, second, and sixth runs in Figure 1 
are encoded using this method. Note that different terminat¬ 
ing codewords are used for runs of black and white pixels. 

Single-color runs that exceed 63 pixels are encoded using 
two codewords. The first is a make-up codeword, selected 



Figure 2 Definition of transition pixels for 
two-dimensional encoding 


b, 


b 2 



a 0 = anchor pixel on the encoding line 

a, = first pixel in the encoding line after a,, 
of opposite color to a 0 

a 2 = first pixel in the encoding line after a, 
of opposite color to a, 

b, = first pixel on the reference line after ao 
of opposite color to a 0 

b 2 = first pixel on the reference line after b, 
of opposite color to b, 
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from Table 2, that represents the largest number of pixels less 
than or equal to the run length. A terminating codeword that 
represents the difference between the number of pixels repre¬ 
sented by the make-up codeword and the total run length is 
then selected from Table 1. Each make-up codeword must be 
followed by a terminating codeword, even if the terminating 
codeword encodes a run of 0. The third, fourth, and fifth runs 
in Figure 1 show this two-part encoding method. 

An examination of the codewords in Tables 1 and 2 will 
show that this run length encoding system produces its maxi¬ 
mum compression for very short runs of black, short to 
medium runs of white, and large expanses of either color. This 
mix is a fair graphical description of a typical typewritten 


Table 1 Terminating codewords for group 3 
one-dimensional run length encoding 

Run Length 

White Codeword 

Black Codeword 

0 

00110101 

0000110111 

i 

000111 

010 

2 

0111 

11 

3 

1000 

10 

4 

1011 

011 

5 

1100 

0011 

6 

1110 

0010 

7 

1111 

00011 

8 

10011 

000101 

9 

10100 

000100 

10 

00111 

0000100 

11 

01000 

0000101 

12 

001000 

0000111 

13 

000011 

00000100 

14 

110100 

00000111 

15 

110101 

000011000 

16 

101010 

0000010111 

17 

101011 

0000011000 

18 

0100111 

0000001000 

19 

0001100 

00001100111 

20 

0001000 

00001101000 

21 

0010111 

00001101100 

22 

0000011 

00000110111 

23 

0000100 

00000101000 

24 

0101000 

00000010111 

25 

0101011 

00000011000 

26 

0010011 

000011001010 

27 

0100100 

000011001011 

28 

0011000 

000011001100 

29 

00000010 

000011001101 

30 

00000011 

000001101000 

31 

00011010 

000001101001 


document and is the model for which the run length codes 
are optimized. The example in Figure 1 achieves a compres¬ 
sion ratio of over 24:1. 

The encoding used in fax transmission is not adaptive; it 
doesn’t change the codewords in reaction to the data. Images 
that don't fit the standard document profile, such as those 
that contain gray-shaded areas (encoded as alternating black 
and white pixels), can actually require more bits encoded than 
unencoded -which explains why those images take longer to 
transmit. 

After each scan line has been encoded, the end-of-line 
(EOL) codeword is appended. The 12 bits of the EOL, 
000000000001, can never occur within a valid encoded scan 


Table 1 continued 

Run Length 

White Codeword 

Black Codeword 

32 

00011011 

000001101010 

33 

00010010 

000001101011 

34 

00010011 

000011010010 

35 

00010100 

000011010011 

36 

00010101 

000011010100 

37 

00010110 

000011010101 

38 

00010111 

000011010110 

39 

00101000 

000011010111 

40 

00101001 

000001101100 

41 

00101010 

000001101101 

42 

00101011 

000011011010 

43 

00101100 

000011011011 

44 

00101101 

000001010100 

45 

00000100 

000001010101 

46 

00000101 

000001010110 

47 

00001010 

000001010111 

48 

00001011 

000001100100 

49 

01010010 

000001100101 

50 

01010011 

000001010010 

51 

01010100 

000001010011 

52 

01010101 

000000100100 

53 

00100100 

000000110111 

54 

00100101 

000000111000 

55 

01011000 

000000100111 

56 

01011001 

000000101000 

57 

01011010 

000001011000 

58 

01011011 

000001011001 

59 

01001010 

000000101011 

60 

01001011 

000000101100 

61 

00110010 

000001011010 

62 

00110011 

000001100110 

63 

00110100 

000001100111 
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line. This property can be used to synchronize after a transmis¬ 
sion error. The EOL codeword is transmitted prior to the first data 


Table 2 Makeup codewords for group 3 
one-dimensional run length encoding 

Run Length 

White Code Word 

Black Code Word 

64 

11011 

0000001111 

128 

10010 

000011001000 

192 

010111 

000011001001 

256 

0110111 

000001011011 

320 

00110110 

000000110011 

384 

00110111 

000000110100 

448 

01100100 

000000110101 

512 

01100101 

0000001101100 

576 

01101000 

0000001101101 

640 

01100111 

0000001001010 

704 

011001100 

0000001001011 

768 

011001101 

0000001001100 

832 

011010010 

0000001001101 

896 

011010011 

0000001110010 

960 

011010100 

0000001110011 

1024 

011010101 

0000001110100 

1088 

011010110 

0000001110101 

1152 

011010111 

0000001110110 

1216 

011011000 

0000001110111 

1280 

011011001 

0000001010010 

1344 

011011010 

0000001010011 

1408 

011011011 

0000001010100 

1472 

010011000 

0000001010101 

1536 

010011001 

0000001011010 

1600 

010011010 

0000001011011 

1664 

011000 

0000001100100 

1728 

010011011 

0000001100101 

1792 

00000001000 

00000001000 

1856 

00000001100 

00000001100 

1920 

00000001101 

00000001101 

1984 

000000010010 

000000010010 

2048 

000000010011 

000000010011 

2112 

000000010100 

000000010100 

2176 

000000010101 

000000010101 

2240 

000000010110 

000000010110 

2304 

000000010111 

000000010111 

2368 

000000011100 

000000011100 

2432 

000000011101 

000000011101 

2496 

000000011110 

000000011110 

2560 

000000011111 

000000011111 
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Table 3 Codewords for vertical mode encoding 

Position 

Pixel Distance 

Codeword 

ai under bi 

0 

1 

ai appears to the right of bi 

1 

011 

2 

000011 

3 

0000011 

a, appears to the right of bi 

1 

010 

2 

000010 

3 

0000010 


line of a page. In addition, six consecutive EOLs are used to 
indicate that the transmission of a document is complete. 

Unlike standard serial data transmission, which is byte- 
oriented, fax transmission is bit-oriented and ignores arbitrary 
byte boundaries. The result of encoding the scan line in Figure 
1 and appending the 12-bit EOL is simply a string of 82 bits. 

If it is necessary to pad out the encoded string, a variable 
length sequence of Os can be used. Fill can appear only be¬ 
tween the end of the encoded data and the EOL codeword, 
never prior to or within a line of data. Thus the final byte- 
aligned encoding (fill shown in bold) for Figure 1 would be as 
follows: 


0001 1110 = IE 
1101 1000 = D8 
1011 1000 = B8 
0001 0010 = 12 
1000 0000 = 80 
0111 0110 = 76 
1001 1010 = 9A 
1100 0000 = CO 
0110 0000 = 60 
0000 0000 = 00 
0000 0001 = 01 

Two-Dimensional Encoding 

In addition to the one-dimensional 
encoding scheme, the CCITT T.4 stand¬ 
ard also describes an optional two- 
dimensional encoding scheme. In this scheme, a single scan 
line is encoded one-dimensionally, as described previously. For 
the next scan line, however, only the differences between the 
new line and the previous line are encoded. A third line is 
then encoded relative to the second, and so on. 

A series of scan lines that contain only minor differences 
can be encoded quite compactly using this method, of course, 
the two-dimensional encoding scheme's increased depend¬ 
ence on the integrity of previous data makes it likely that a 
single error could propagate unchecked, making the docu¬ 
ment unreadable. 
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To limit the effects of an error, an arbitrary limit of K re¬ 
lated lines is set. In other words, after a one-dimensionally 
encoded line is transmitted, at most K-1 successive two- 
dimensionally encoded lines will be transmitted. The recom¬ 
mended maximum value of K is 2 for standard vertical resolu¬ 
tion, and 4 for higher resolution. (The value for K is established 
during the negotiation phase of the fax session.) 

The two-dimensional encoding procedure begins with the 
one-dimensional encoding of the first line in a related group. 
This line is designated the reference line. The next line to be 
encoded is called the encoding line. The reference line and 
encoding line are compared and several key pixels are iden¬ 
tified. 

These key pixels are known as transition pixels and are 
simply pixels whose color is different than the preceding pixel 
in the same line. For consistent encoding, all lines are as¬ 
sumed to begin on an imaginary white pixel positioned prior 
to the first real pixel in the line. Figure 2 shows the juxtaposi¬ 
tion of a portion of a reference line and the corresponding 
portion of a encoding line and defines the five categories of 
transition pixels. These categories are as follows: 
a 0 -The anchor pixel of the encoding line. Initially, a 0 points 
to the imaginary white pixel that begins each encoding 
line. As the encoding proceeds in sections, the position of 
ao is redefined by the algorithm, 
ai —The first transition pixel on the encoding line to the right 
of a o. 

a 2 -The first transition pixel on the encoding line to the right 

Of fli. 

bt —The first transition pixel on the reference line that is both 
to the right of oo and of the opposite color. 
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b 2 —The first transition pixel on the reference line to the right 

of a u 

The next step is to determine the encoding mode, based 
on the relative positions of the identified transition pixels. The 
procedures described below apply to encoding. Decoding is 
performed by identifying unique codewords and expanding 
the pixels. 

When b 2 appears to the left of a i, the situation is defined 
as pass mode and the codeword 0001 is generated. The 
receiver interprets this as an instruction to fill pixels of the 
current a o color from position a o to the encoding pixel just 
before b 2 . The anchor pixel ao is redefined to be the pixel in 
the encoding line directly below b 2 in preparation for the con¬ 
tinuation of the algorithm. Figure 3a illustrates this situation. 

If pass mode is not detected, the position of pixel a\ rela¬ 
tive to pixel bi is determined. If oi appears within three pixels 
to the left or right of bi, this situation is defined as vertical 
mode: it is illustrated in Figure 3b. The relative distance be¬ 
tween ai and bi is encoded using the codewords shown in 
Table 3. The anchor pixel a o is then redefined to be at position 
ai in preparation for the continuation of the procedure. At the 
receiver, pixels of the current ao color are written from the 
current ao position to the current ai, its position being deter¬ 
mined relative to b 2 as given by the codeword. 

If pass mode is not detected and ai is positioned further 
than three pixels from bi, the arrangement is defined as 
horizontal mode: it is illustrated in Figure 3c. In this case, the 
codeword 001 and the one-dimensional codewords for the 
runs ao-ai and ai-02 are transmitted. The anchor pixel ao is 
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then redefined to be at position <32 in preparation for the con¬ 
tinuation of the procedure. At the receiver, pixel runs of the 
appropriate colors and lengths are written as encoded. 

Two Wrinkles 

One of the most unusual aspects of encoding data for a fax 
modem is dealing with the apparent bit reversal that takes 
place in each byte. The UARTs used in PCs serialize a byte by 
transmitting the least-significant bit first. The receiving UART 
does the complementary operation, placing the first serial bit 
to arrive in the least-significant bit position of a byte. The bit- 
order of exchanged bytes is thus preserved. 

But it’s impossible for fax machines to work according to 
the same type of logic. There are no natural byte boundaries 
in fax data bit streams — there is no least-significant bit. In¬ 
stead, a fax machine sends each bit from first-generated to 
last-generated. 

These two differing philosophies clash when a string of bits 
from a remote fax machine is received by a fax modem and 
reported to the PC’s UART in the order they were received. 
The UART — knowing no better, places the first bit it gets into 
the low order position of a byte. It proceeds in this fashion 
until the byte is filled, then passes it to the PC. As a result, the 
bits in the byte passed to the application appear to be 
reversed relative to the order in which they were sent by the 
originating fax machine. The bytes, however, are not in 
reverse order. PC applications that communicate through a fax 
modem must emulate and anticipate this bit reversal. 

A second consideration is the special handling that must 
be given to occurrences of the ASCII DLE character (lOh). 
When exchanged between the PC and the fax modem, DLE 
functions as an escape character. A DLE followed by an ETX 
character (03h) is used to signal end-of-data. A DLE followed 
by another DLE translates to the single byte lOh. A DLE fol¬ 
lowed by any other character is invalid. 

The PC formats fax data and sends it (via the serial port) to 
its local fax modem. After the individual bits of each byte are 
reversed (for the reason described above), each byte must be 
checked to see if it has the value lOh (DLE). If so, an additional 
DLE must be inserted into the data stream immediately fol¬ 
lowing the original DLE. The second DLE will be removed by 
the fax modem before the data is transmitted over the 
telephone line. 

During reception, the opposite condition occurs. If the fax 
modem receives a single DLE, it sends two successive DLE 
characters to the PC. The PC must expect and detect this and 
eliminate one of the DLE characters. Note, however, that this 
DLE detection must occur before the received data is bit- 
reversed. 

Conclusion 

Some of the rules that govern fax operation may seem 
arcane, springing as they do from a heterogeneous legacy of 
electro-mechanical devices and discrete electronics. It is the 
huge installed base of dedicated fax machines and the re¬ 
quirements that PC fax modems be compatible with them, 
however, that drives the standards. The one-dimensional and 
two-dimensional fax encoding schemes described in this ar¬ 
ticle are part of those standards. □ 
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NETROOM v3.0 and the Cloaking API 

Thomas W. Olsen 


The original PC architecture limited DOS programs to about 
640Kb of memory. This limitation created a niche market for 
numerous memory management utilities — including Quarter¬ 
deck QEMM-386, Qualitas 386MAX, and Helix NETROOM, to 
name a few —that liberate previously unused memory in the 
first megabyte, and make it possible to load more device 
drivers and TSRs. Even Microsoft threw its hat into the ring 
with the release of MS-DOS 5.0 and, more recently, MS-DOS 
6 . 0 . 

Most of these products are built upon a similar technical 
foundation: a special device driver switches the CPU into so- 
called Virtual-8086 (V86) mode (this assumes you have at least 
an 80386), backfills unused conventional memory with ex¬ 
tended memory (using the processor’s virtual memory 
capabilities), and loads DOS into the High Memory Area (HMA), 
the 64Kb segment just above the 1Mb boundary. Further, 
most memory managers provide a means of optimizing the 
load sequence of device drivers and TSRs in config.sys and 
autoexec.bat files, and tie the DOS Protected Mode Interface 
(DPMI), Virtual Control Program Interface (VCPI), extended 
Memory Specification (XMS), and Expanded Memory Specifica¬ 
tion (EMS) into a single neat package. Windows compatibility is 
an absolute requirement, too. 

The similarities between memory managers end there, 
however, because each product employs its own bag of tricks 
to gain every last ounce of RAM. Some load DOS data struc¬ 
tures (files, buffers, stacks) and command, com into a high por¬ 
tion of memory. Others eke out another 32Kb from the sel- 
dom-used monochrome display area. QEMM-386 maps several 
large segments of memory with "stealth" into a smaller net 
address space. 386MAX “shrinks and grows” the Upper 
Memory Blocks (UMBs) on demand and “compresses” the ROM 
BIOS area. Before counting your blessings, though, you should 
be aware that some of the most daring optimizations play 


havoc with Microsoft Windows memory management and 
must be disabled. You may want to look at James Lawless's 
article in the August 1993 issue of Windows/DOS Developer’s 
Journal for a technical exploration of techniques for getting 
more real-mode memory. 


Product information 


NETROOM V3.0 

Helix Software Company 
47-09 30th Street 
Long Island City, New York 11101 
Phone: (800) 451-0551 
FAX: (718) 392-4212 


Requires: An IBM-compatible PC with at least 1Mb of 
memory, DOS 3.x or later, or DRDOS 5.x or later. 

Price: $99.95 for one user, $179 for four users, $399 for ten 
users, or $1,495 for 50 users. Upgrade licenses cost $39.95 
for a single user, $79.95 for four users, $189.95 for ten 
users, $799.95 for 50 users, or $1,499.95 for 100 users. 

Summary: NETROOM is a memory management package 
that now includes an API for developers who want to take 
advantage of 32-bit memory in constructing resident DOS 
programs. By using NETROOM's “cloaking API", you can cre¬ 
ate TSRs that reside in protected-mode memory and leave 
only a tiny footprint in conventional memory. 


Thomas Olsen is the president of Larger than Life Publishing, a firm that specializes in Windows Multimedia software. He can be 
reached on the CompuServe Information Service at 76450,1767. 
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Memory managers don’t fall into the 
class of products typically reviewed in 
this magazine. The new version of 
NETR00M, however, provides an API for 
developers that helps them create resi¬ 
dent DOS programs that use very little 
conventional memory. This review brief¬ 


ly covers NETROOM’s general capabilities 
and then focuses on its API for DOS 
developers. 

Enter NETR00M 

One of the things that sets Helix 
Software's NETR00M v3.0 apart is its 


Listing 1 clockclk.asm - Demonstrating NETROOM’s cloaking API 


1 

| Filename : 

CLOCKCLK.ASM - System Clock Cloaking Device 

1 

| Version : 

1.0 


j Author : 

Thomas W. Olsen, CIS: [76450,1767] 


| Assembler : 

Microsoft Macro Assembler (MASM) v6.0B 

1 

j Build Note: 

i 

ml /Zm clockclk.asm 

1 

1 


• 386P 

include CLOAKAPI.INC 


Constant & Structure Definitions 


TICKS PER SECOND 

EQU 

18 




TRUE “ 

EQU 

1 




FALSE 

EQU 

0 




CR 

EQU 

13 




LF 

EQU 

10 




VIDEO SEGMENT 

EQU 

0B800h 




DISPLAY COLUMN 

EQU 

75 * 2 




BIOS SEGMENT 

EQU 

0 




TIMER_OFFSET 

EQU 

46Ch 




XMSMoveStructure 

struc 





BlockLength 

dw 

0.0 



SourceHandle 

dw 

0 

;0=Conventional 

Memory 

SourceOffset 

dw 

0,0 



DestHandle 

dw 

0 

;0<onventional 

Memory 

DestOffset 

dw 

0,0 

;FlatOffset or Seg:0ffset if Conventional 

XMSMoveStructure 

ends 






V86 Entrypoint Code 


V86 CODE Segment Public Usel6 Byte 'V86 1 

Assume cs:V86_C0DE, ds:V86_C0DE, ss:STACK 

V86ResidentCodeBegin label byte 


OldTimerOffset 

dw 

? 

OldTimerSegment 

dw 

? 

Reentrant 

dw 

FALSE 

Ticks 

db 

TICKS PER SECOND 


V86_TimerHandler proc far 



pushf 

call 

dword ptr cs:01dTimer0ffset 

;Call Original Timer Tick 


emp 

cs:Reentrant, TRUE 

;Are We Becoming Reentrant? 


je 

UU0 



dec 

cs:Ticks 



jz 

UU1 

;Has One Second Expired? 

QUO: 

iret 


;Abort If Reentrant 

@@1: 

mov 

cs:Reentrant, TRUE 

;Set Reentrant Flag 


mov 

cs:Ticks, TICKS PER SECOND 

;Reset Counter to One Second 


int 

2CH 

;RM386 Transition to PM Code 

UU2: 

sti 


;Enable Interrupts 


mov 

cs:Reentrant, FALSE 

•.Clear Reentrant Flag 


retf 

2 

;Return Flags 


V86 TimerHandler endp 
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unique "cloaking” technology. Instead of 
trying to squash what little remains of 
the first megabyte of memory, 
NETROOM moves ROM BIOS, Video BIOS, 
device drivers, and TSRs out of conven¬ 
tional memory into extended memory, 
and replaces them with tiny stub 


programs, or “cloaking devices.” Cloaked 
programs run in full, 32-bit protected 
mode without need of a DOS extender, 
and have access to the entire 4Gb ad¬ 
dress space of 80386-class machines. 

With ROM and Video BIOS Cloaking 
enabled, NETROOM effectively increases 


DATA BOSS 

USERS 


Listing 1 

continued 


V86ResidentCodeEnd label byte 



Psp 

dw 

0 


BaseSegment dw 

0 


XmsHandle dw 

0 


XmsAddress dd 

0 


CloakingDeviceLoaded db 

CR,LF,"Systan Clock Cloaking Device Loaded.",CR,LF,"$" 


ErrorRM386NotLoaded db 

CR,LF,"RM386 Not loaded.'',OR,LF,"$" 


ErrorXMSNotLoaded db 

CR,LF,"XMS Memory Manager Not Loaded.",CR,LF,"$" 


ErrorOutOfMemory db 

CR,LF,"Insufficient Extended Memory.",CR,LF,"$" 


ErrorCannotLockMemory db 

CR,LF,"Cannot Lock Memory Region.",CR,LF,"$" 


ErrorCannotRelocateCode db 

CR.LF,"Cannot Load Protected Mode Code.".CR.LF, 


ErrorCannotExecCode db 

CR.LF,"Cannot Activate Protected Mode Code.'',CR.LF,"$“ 


XMSHoveStruc XMSMoveStructure <> 

V86 

Main proc 

near 



public 

V86_Main 



mov 

ax, 351Ch 



int 

21h 

;D0S Get Interrupt Vector ICh 


mov 

cs:01dTimer0ffset, bx 



mov 

cs:01dTimerSegment, es 

;ES:BX -> Old ICh Vector 


mov 

cs:Psp, ds 

;Save PSP Segment 


mov 

cs:BaseSegment, ds 



add 

cs:BaseSegment, 6 

;Move V86 TimerHandler Code Into PSP:60h 


mov 

ax, cs 

; to Minimize Our Memory Footprint Even More 


mov 

ds, ax 



mov 

si, offset V86ResidentCodeBegin 


mov 

es, cs:BaseSegment 



xor 

di, di 



mov 

cx, offset V86ResidentCodeEnd 


sub 

cx, offset V86ResidentCodeBegin 


cld 




rep 

movsb 

;Copy Code into PSP (Overlays FOB Area) 


mov 

ax, cs 



mov 

es, ax 



mov 

ax,3567h 

;Is EMS Manager Present? 


int 

21 h 



mov 

ax, es 



or 

ax, bx 



jne 

@@3 



mov 

dx, offset ErrorRM386NotLoaded 


jmp 

@@10 


m-. 





mov 

ax,5BF0h 

;Is RM386 Manager Present? 


int 

67h 



or 

ah,ah 



je 

@@4 



mov 

dx,offset ErrorRM386NotLoaded 


jmp 

@@10 


@@4: 





mov 

ax,4300h 

;Is XMS Manager Present? 


int 

2fh 



cmp 

al,80h 



je 

@@5 



mov 

dx,offset ErrorXMSNotLoaded 


jmp 

@@10 


@@5: 





mov 

ax,4310h 

;Get XMS Manager Address 


int 

2Fh 



mov 

word ptr cs:XmsAddress, 

bx 


mov 

word ptr cs:XmsAddress+2, es 


mov 

ax, offset PMCodeEnd 

;Compute Amt of XMS Memory to Hold PM Code 


sub 

ax, offset PMCodeBegin 
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Listing 1 

continued 



shr 

ax, 10 

;Convert Bytes -> Kilobytes 


inc 

ax 

;Round Up 


mov 

dx.ax 



mov 

ah,9 

;XMS Allocate Memory 


call 

dword ptr XmsAddress 



or 

ax, ax 

;Successful? 


jne 

@@6 



mov 

dx,offset ErrorOutOfMemory 


jmp 

@@10 


@@6: 





mov 

XmsHandle,dx 

;Save Handle 


mov 

ah, Och 

;XMS Lock Memory Region 


cal 1 

dword ptr XmsAddress 



or 

ax, ax 

;Successful? 


jne 

@@7 



mov 

dx,offset ErrorCannotLockMemory 


jmp 

@@10 


@@7: 





mov 

ax, XmsHandle 

;Move PM Code into XMS Alloc'd Block 


mov 

XMSMoveStruc.DestHandle, 

ax 


xor 

eax, eax 



mov 

ax, offset PMCodeEnd 



xor 

ebx, ebx 



mov 

bx, offset PMCodeBegin 



sub 

eax, ebx 

;BlockLength = PMCodeEnd - PMCodeBegin 


shr 

eax, 4 

•.Convert to Paragraphs 


inc 

eax 

;Round Up 


shl 

eax, 4 

•.Convert Back to Bytes 


mov 

dword ptr XMSMoveStruc.Blocklength, eax 


mov 

ax, PM CODE 



mov 

XMSMove$truc.Source0ffset+2,ax 


mov 

si.offset XMSMoveStruc 



mov 

ah,0bh 



call 

dword ptr XmsAddress 



or 

ax,ax 



jne 

@@8 



mov 

dx,offset ErrorCannotRelocateCode 


jmp 

@@10 


m-. 





mov 

si, cs:BaseSegment 

;ESI Uniquely Identifies Our V86 Stub 


shl 

esi, 16 



mov 

si, offset @@2 

;Pass INT 2CH Iret Address to PM Init 


mov 

dx, XmsHandle 



mov 

cl, 1 

;32-Bit Code 


mov 

ah, 82h 

;RM386 Transition to PM Init Code 


call 

dword ptr XmsAddress 



or 

ax, ax 

•.Successful ? 


jne 

@@9 



mov 

dx, offset ErrorCannotExecCode 


jmp 

@@10 


@@9: 



;PM Code is Running...Grab V86 Ints and TSR 


mov 

dx, offset V86 TimerHandler 


mov 

ax, cs:BaseSegment 

;V86 TimerHandler Code Seg Now Equals PSP+6h 


mov 

ds, ax 



mov 

ax, 251Ch 



int 

2 lh 

;DOS Set Interrupt Vector ICh 


mov 

es, cs:Psp 

;Point to PSP 


mov 

es, es: [2CH] 

;Get Environment Segment 


mov 

ah, 49h 

•.Deallocate Environment, Too. 


int 

21 h 



mov 

ax, cs 



mov 

ds, ax 



lea 

dx, CloakingDeviceLoaded 


mov 

ah, 9 



int 

21 h 



mov 

dx, cs:BaseSegment 



sub 

dx, cs:Psp 



shl 

dx. 4 



add 

dx, offset V86ResidentCodeEnd 


shr 

dx, 4 



inc 

dx 



mov 

ax,3100h 

;Terminate & Stay Resident 


int 

21h 


@@10: 





mov 

ax,cs 

;Error Occurred ... Cleanup Time 


available RAM by as much as 96Kb and, 
as a collateral benefit, upgrades your 
ROM and Video BIOS (without pulling a 
chip) to the latest version written by 
Award Software. NETROOM supplies spe¬ 
cialized BIOS programs for ISA, EISA, 
PS/2s, and Laptop Advanced Power 
Management (APM). NETROOM also in¬ 
cludes an assortment of cloaked utilities 

— a disk cache, RAM disk, screen saver, 
video accelerator, and antivirus monitor 

— so you can stock your PC to the gills 
without fretting over lost memory. 
(Steven Spielberg fans will want to 
check out NETROOM's JURASSIC screen¬ 
saver.) 

With NETROOM loaded, my test PC 
has over 634Kb of usable DOS memory 
and room to spare in the UMBs. Still 
strapped for memory, you say? 
NETROOM contains a special utility 
called STRETCH that makes nearly 
720Kb available to text-based VGA 
programs by mapping the video BIOS 
and monochrome display areas into the 
DOS memory arena. NETROOM also 
provides a facility by which you can set 
up separate and logical 576Kb EMS- 
mapped “Virtual Machines” that switch 
quickly enough to give the illusion of 
multitasking under DOS. 

Installation and Operation 

When you first run Setup from the 
distribution diskette, it becomes ap¬ 
parent that Helix took great pains to 
make NETROOM as crashproof as pos¬ 
sible. The Customize utility lets you 
tune NETROOM to one of three possible 
configurations: aggressive, conservative, 
and custom. The first two configurations 
are nearly automatic — push a button, 
and the job gets done with minimal 
user intervention. The third alternative, 
custom, produces a menu of options 
that enable or disable various aspects 
of NETROOM's operation. You can abort 
the installation at any point and 
NETROOM will restore config.sys, 
autoexec.bat, and system.ini files to 
their original state. This is especially im¬ 
portant because NETROOM has to 
reboot your PC several times during the 
installation procedure. 

If you use disk compression software 
such as Stacker, SuperStor, or MS-DOS 
6.0, you will be glad to note that 
NETROOM automatically detects and 
compensates for swapped boot drives. 
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@@ 11 : 


V86_Main endp 


V86 CODE ENDS 


Protected Mode Code 


jmp 


PMDataSelector dw 
V86DataSelector dw 
FlatSelector dw 
PassAlong df 
RM386_API df 
VideoSelector dw 


Competitors 386MAX and QEMM-386 re¬ 
quire that you install their products 
manually when disk compression is 
being used — an annoying diversion. If 
Customize does not recognize your 
compression software, you can instruct 
it on the particulars with a set of ex¬ 
plicit command-line parameters. 

NETROOM provides integrated online 
help and a text editor for last-minute 
changes. 

NETROOM does have its share of 
minor problems. It failed to load on an 
ALR BusinessVEISA 386 PC equipped 
with 20 megabytes of RAM. This prob¬ 
lem disappeared after the “Protected 
Mode Memory Check” was disabled on 
the Custom Setup menu. Customize 
stripped a label called “:LOADHlGH" 

(granted, not the best choice for a label) 
from autoexec.bat on the erroneous 
assumption that it was a reference to 
the DOS LOADHIGH command. Changing 
the label name fixed the problem. Win¬ 
dows could not create a permanent 
swapfile with the Cloaking Disk Cache 
loaded. This was resolved by invoking 
the Cloaking Disk Cache with a 
parameter of NDH (No Device Hook). 

NuMega's SoftICE/Windows debugger garbled the screen 
display when Video Cloaking was enabled. This problem disap¬ 
peared when Video Cloaking was disabled on the Custom 
Setup menu; however, the actual culprit turned out to be an 
old, incompatible Windows display driver. Apparently, the 
driver tried to access the Video BIOS area directly, and didn’t 
realize that NETROOM had relocated it into extended memory. 
Upgrading to the latest Windows display driver made Video 
Cloaking possible again. All in all, these problems weren't very 
significant, and, to its credit, NETROOM recovered perfectly in 
each instance. 

Once installed, NETROOM runs transparently and requires 
no overt maintenance. It’s a good idea to run Customize after 
changing config.sys or autoexec.bat to ensure that you’re 
getting the optimum amount of available memory. NETROOM 
includes a mouse-driven GUI diagnostic program called Dis¬ 
cover that provides a lot of information about conventional, 
UMB, and extended memory contents, interrupts, network 
shell, benchmarks, and EMS/XMS pages. Discover is a handy 
alternative to the Norton Utilities Sysinfo program, and makes 
it easy to tune your configuration as needs change. 

The Cloaking API 

Helix Software recently released details about its NETROOM 
Cloaking API, so developers can take advantage of the same 
cloaking technology in their own device drivers and TSRs. The 
Cloaking API consists of nearly 50 function calls that manipu¬ 
late protected-mode selectors, set callbacks, monitor ports, 
push and pop the current machine state, and perform inter¬ 
rupts. Each call is handled by the NETROOM rm386.exe device 


mov 

ds,ax 


push 

dx 


mov 

dx.XmsHandle ;Was 

any XMS Allocated? 

or 

dx.dx 


je 

@@11 ;Yes 

... Free It Before Terminating 

mov 

ah,0ah 

cal 1 

dword ptr csrXmsAddress 


pop 

dx ;D0S 

Display Error Message 

mov 

ah,9 


int 

2 lh 


mov 

ax,4C00h ;Terminate. 

int 

2 lh 



PM_C0DE Segment Public Use32 Para 'PMCODE' 
Assume cs:PM_C0DE, ds:PM_C0DE 

PMCodeBegin label byte 


PM Init 


.\* T, NC> 
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Listing 1 

continued 


V86Address dd 0 


Hours 

dw ? 

db 


Minutes 

dw ? 

db 0 


PM Init proc near 


public 

PM Init 


mov 

PMDataSelector, ds 


mov 

V86DataSelector, es 


mov 

FlatSelector, gs 


mov 

V86Address, esi 


mov 

ax, get passalong 

;Get Head of the PassAlong DaisyChain 

int 

2CH 


mov 

dword ptr ds:PassAlong, 

ebx 

mov 

word ptr ds:PassAlong+4, dx 

mov 

ebx, offset PM TimerHandler 

mov 

dx, cs 


mov 

ax, set passalong 

;Make Ourselves the Head of DaisyChain 

int 

2CH 


retf 

PM_Init endp 

PM TimerHandler 

PROC FAR 


public 

PM TimerHandler 


cmp 

eax, cs:V86Address 

;Were we Called by V86 TimerHandler? 

je 

@@12 


cmp 

word ptr cs:[PassAlong+4],0 

je 

@@13 

;Are there Any Other Passalongs? 

jmp 

fword ptr cs:PassAlong 

;Yes ... DaisyChain to Next 

@@12: 

cal 1 

PM ShowClock 

;Display the Clock 

stc 

@@13: 

ret 

PM_TimerHandler 

ENDP 


PM ShowClock proc near 


public 

PM ShowClock 


mov 

ds, cs:PMDataSelector 


mov 

es, cs:V86DataSelector 


xor 

edi, edi 


mov 

di, BIOS SEGMENT 

;Get Master Clock Count from 

shl 

edi, 4 


add 

edi, TIMER OFFSET 

; V86 BIOS Data Area 

mov 

eax, es:[edi ] 

; V86 0:[46Ch] —> PM V86DataSelector: [0*10h+46Ch] 

xor 

edx, edx 


mov 

ecx, 65544 


div 

ecx 


push 

eax 

;EAX = Hour, EDX = Remainder 

xchg 

eax, edx 


xor 

edx, edx 


mov 

ecx, 1092 


div 

ecx 

;EAX = Minutes, EDX = Remainder 

push 

eax 


pop 

eax 


cal 1 

PM HexToAscii 

;Input: AX = Unsigned Hex Integer 

mov 

Minutes, ax 

;0utput: AX = 2-Byte ASCII Representation 

pop 

eax 


cal 1 

PM HexToAscii 

;Input: AX = Unsigned Hex Integer 

mov 

Hours, ax 

;0utput: AX = 2-Byte ASCII Representation 

mov 

esi, offset Hours 

;Display Time Directly to Video Buffer 

xor 

edi, edi 


mov 

di, VIDEO SEGMENT 


shl 

edi, 4 


add 

edi, DISPLAY COLUMN 

; V86 0:[B800h] —> 

cld 


; PM V86DataSelector: [B800h*10h+DI SPLAY C0LUMN*2] 

mov 

ah, es:[edi+l] 


@@14: lodsb 


;Load Character from PM Data Area 

and 

al, al 

; End of String? 

jz 

@@15 



driver, which hooks up INT 2Ch to a 
protected-mode callback routine. 

Writing a cloaked program is very 
similar to writing a typical TSR, with 
two exceptions. First, you've got to be 
willing to get your hands dirty and code 
almost entirely in assembly language. 
That shouldn't be a problem, since most 
TSR developers build their programs 
with lean space constraints in mind. 
Helix recommends Microsoft MASM 6.0. 
It seems that MASM 5.1 has problems 
resolving certain protected-mode in¬ 
structions and should be avoided. 
Second, you must understand the 
general workings of the 386/486 
protected-mode architecture and 
programming. One of the best sources 
of information on the subject is the 
Intel 386DX Microprocessor 
Programmer’s Reference Manual. To be 
honest, though, the Cloaking API does 
most of the work for you. 

Here’s how it works. Every cloaked 
TSR consists of two components: one 
that starts in V86 mode and another 
that runs in protected mode. The TSR 
V86 initialization code has several jobs 
to accomplish. It first determines 
whether the rm386.exe (the NETROOM 
device driver) has been loaded and 
whether the XMS manager can allocate 
sufficient extended memory to accom¬ 
modate its protected-mode portion. 
Then, the V86 portion of the TSR copies 
the protected-mode portion into ex¬ 
tended memory using the XMS Move 
Function (OxOB), and transfers control to 
the protected-mode entry point of your 
TSR with the XMS Transition Function 
(0x82). The latter function is not an ordi¬ 
nary component of XMS but an exten¬ 
sion supplied by the cloaking API. 

The protected-mode initialization 
code saves all of the selectors that 
rm386.exe sets up for its use. Since the 
protected code has no separate "data 
segment" per se, the DS register refers 
to the same linear address as CS but 
has a read/write privilege level. The GS 
register refers to a flat-mapped selector. 
You can use the ES register to access 
the entire V86 address space. For ex¬ 
ample, V86 address 0xB800:0x200 
would have an equivalent protected- 
mode address of ES:0xB8200 (i.e., 
ES:0xB800*0xl0+0x200). ESI contains 
the segment/offset return address of 
the V86 stub which will invoke the 

(continued on page 42) 
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Listing 1 continued 


stosw ;Move Character to V86 Video Buffer 

jmp @@14 

@@15: 

ret 

PM_ShowClock endp 
PM_HexToAscii proc near 


push 

ecx 


push 

edx 


xor 

edx, 

, edx 

xor 

ah. 

ah 

mov 

cx, 

10 

div 

cx 


shl 

al, 

4 

or 

al, 

dl 

shl 

ax. 

4 

xchg 

ah. 

al 

shr 

ah, 

4 

add 

ax, 

3030h 

pop 

edx 


pop 

ecx 


ret 

HexToAscii 

endp 



PMCodeEnd label byte 


PM CODE Ends 


STACK Segment Stack 'STACK' 

dw 512 DUP(O) 

STACK Ends 

End V86_Main 
; End of File 
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(continued from page 38) 

cloaked protected-mode code. ESI serves to uniquely identify 
the V86 stub program —think of it as a tag or signature of sorts. 

Next, the protected-mode initialization code uses the cloak¬ 
ing API I NT 0x2C, “Get Passalong Function” (0x08), to deter¬ 
mine the head of the pass-along daisy chain. rm386. exe uses 
this chain to route incoming V86 requests to their appropriate 
protected-mode code destinations. Before finishing, the 
protected-mode initialization code uses the cloaking API INT 
0x2C, “Set Passalong Function” (0x09), to make itself the head 
of the pass-along daisy chain. After the protected-mode in¬ 
itialization code has finished, the V86 initialization code 


resumes execution. It checks to see whether the XMS Transi¬ 
tion Function (0x82) was successful and, if so, sets appropriate 
V86 stub interrupt vector(s), deallocates any unused memory, 
and executes the DOS Terminate-but-Stay-Resident call. 

At this point, the only thing in V86 memory is a tiny frag¬ 
ment (or stub) of the original V86 initialization code. When the 
stub is interrupted, it transfers control via cloaking API INT 
0x2C to the head of the protected-mode, pass-along daisy 
chain, m386.exe sets up the EAX register with the V86 stub 
return address. When a request comes down the daisy chain, 
each pass-along checks whether the stub address in EAX 
matches that of its V86 partner. If not, it relays the request to 
the next pass-along in the daisy chain. It’s a lot like chaining 
interrupt vectors together. 

A potential problem comes to mind 
with this scheme. What happens if you 
try to load a cloaked TSR in a Windows 
DOS box and the V86 stub address just 
happens to correspond with that of 
another stub in a completely separate 
DOS box? Would somebody else’s pass¬ 
along mistakenly process your inter¬ 
rupt? The answer is no —this can’t hap¬ 
pen because the cloaking API will not 
allow you to load cloaked TSRs in a 
Windows DOS box. 

clockclk.asm (Listing 1) illustrates the 
basic structure of a cloaked TSR. Its only 
aspiration is to display the current time in 
the upper right-hand corner of the screen. 
You will note that the contents of 
V86_C0DE and PM_C0DE segments reside in 
V86 and protected mode, respectively. 
clockclk.asm hooks up V86_Timer- 
Handler to the V86 timer tick interrupt 
(Ox 1C) and passes control once a second 
to a protected-mode pass-along named 
PM_TimerHandler. The latter reads the 
BIOS master clock tick count DWORD lo¬ 
cated at V86 address 0:0x46C, converts it 
into an ASCII string, and copies the result 
to the video buffer. 

clockclk.asm (Listing 1) requires 
cloakapi.inc, which is too large to 
print here; it is included with the code 
disk (see the table of contents for code 
availability). Helix says they are planning 
to place cloakapi.inc on CompuServe 
in the PCVENG forum (it has not ap¬ 
peared as of this writing) and that it is 
available on disk at the request of 
registered users. 

clockclk.asm contains a couple of 
noteworthy optimizations. First, it deal¬ 
locates the DOS environment, copies all 
of the resident V86 code into the Pro¬ 
gram Segment Prefix (PSP) at offset 
0x60, and normalizes CS:IP so that all 
address references are the same (i.e., 
CS=PSPseg+0x60/0xl0,IP=0x0). This 
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reduces its overall footprint to a mere 160 bytes — not a bad 
price to pay for a memory-resident clock. Next, V86_Timer- 
Handler switches to protected mode only at one-second in¬ 
tervals, rather than with each timer tick, since a switch on 
each timer tick might be a little too expensive. Last, clock- 
clk.asm sets a flag to prevent the unlikely possibility of 
reentrant timer tick interrupts. 

Helix Software distributes the NETROOM cloaking API on 
diskette at the request of registered users and through the 
CompuServe PCVENG Forum. There is no formal documentation 
yet —just a couple of source examples and an include file — 
but Helix assures me that complete documentation is 
forthcoming. Even without documentation, most programmers 
should find the API to be pretty intuitive, the source examples 
good, and development time relatively short. 

Summary 

If you’re looking for the absolute maximum amount of DOS 
memory, Helix Software’s NETROOM is a solid choice. Its cloak¬ 
ing technology and integrated BIOS code deliver a high degree 
of DOS and Windows compatibility without losing flexibility. 
NETROOM has one of the easiest installation procedures 
among memory managers to date, the utilities are superb, 
and the technical support staff is very knowledgeable. 

The NETROOM cloaking API offers developers a means of 
making their DOS products more lean and effective, and can 
even be viewed as an alternative to existing DOS extender 
technology. [NETROOM has announced version 1.1 of the 
Cloaking Specification and the Cloaking Developers Kit. Cloak¬ 


ing version 1.1 will allow Cloaked applications to run with 
NETROOM and third-party memory managers, such as DOS 6’s 
EMM386. The Cloaking Developers Kit, due to be available in 
October 1993, includes several Cloaking enhancements and 
the generic Cloaking module. Cloaking version 1.1 fully sup¬ 
ports any existing Cloaking version 1.0 application.] Helix 
Software will license its rm386.exe device driver for distribu¬ 
tion with products that incorporate cloaking technology, its 
low cost alone (see product information box) makes it a viable 
option. Of course, the only hitch is that users of competing 
products such as QEMM-386 and 386MAX might not be willing 
to substitute rm386.exe for their memory managers. It has 
also been rumored that a future version of MS-DOS will place 
all operating system code and data in extended memory just 
like the NETROOM cloaking API, but no dominant standard has 
emerged yet. Perhaps one has just arrived. □ 
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■ User Report 


LibTools 

Brian Abbott 


Proper library management results in better overall ap¬ 
plication development, saving programmers considerable time 
and aggravation, but library management can be a time-con¬ 
suming and tedious chore. Consequently, this necessary step 
of the programming cycle is often relegated to the few mo¬ 
ments when no deadline beckons. LibTools, from Integrated 


Product Information 


LibTools vl.02 

Integrated Development Corporation 
190 Main Street 
Post Office Box 592 
Hampstead, NH 03841 
Sales (800) 333-3429; 

Support (603) 329-5522; FAX/BBS (603) 329-4841; 
CompuServe 70441,2465 


Price: $149. Includes 30-day, money-back guarantee, 30 
days of free phone technical support, and unlimited free 
CompuServe and BBS support. 

Summary: LibTools handles both Microsoft and Borland 
libraries and provides faster library management with more 
capabilities than Microsoft’s LIB or Borland's TUB. 


Development Corporation, changes all that. It’s fast, easy to 
use, and produces detailed, useful reports. 

Why . libs! 

Anyone who has compiled and linked a program knows 
something about. lib files. A library is a file that contains one 
or more object (.obj) files along with a specially formatted 
index so that the linker can quickly locate object modules 
required by the program being linked. Every C compiler sup¬ 
plies one or more . lib files —they contain the modules that 
define the “runtime library’’ for the language. 

If you have a set of common routines, you can group them 
into a library file for easy upkeep. Creating and using your 
own library is much more convenient than trying to manage 
individual object modules. Since all of your common routines 
will be in just one file, when you make a change to a func¬ 
tion, you update it in one place instead of in myriad develop¬ 
ment directories. Your linker will find and link any of those 
routines that are referenced in your program files —and only 
those that are referenced —every time. 

Using libraries can also make link times faster, since the 
linker has only to open and close a single . lib file rather than 
multiple . obj files. . I ib files can also take up less disk space, 
because of the minimum cluster size of hard drives. 

lib.exe and tlib.exe 

The two most common library managers are Microsoft’s 
lib.exe (LIB) and Borland’s tlib.exe (TLIB). These two library 
managers come with the Microsoft and Borland compilers, 


Brian Abbott has been programming since 1977 and currently owns a small consulting firm that specializes in multiuser database 
applications. You can contact him at the InfoSystems Group, 3624 Royal Crest Dr., Montgomery, AL 36109, (205) 244-7840. 








45 


respectively, and allow you to create, add, edit, delete, and 
update . I ib files. Unfortunately, the latest versions of these 
library managers do not work on their counterpart’s libraries: 
you can’t use Microsoft’s LIB with Borland C++ object modules, 
and TUB fails on Microsoft C v7 object modules. 

Integrated Development Corporation’s LibTools performs 
the same operations as LIB and TLIB. It works on both Micro¬ 
soft and Borland object modules (and all other object modules 
that abide by one of these standards). In addition, LibTools 
handles wildcard file specifications on the command line 
(which neither LIB nor TLIB does). It is completely configurable 
via a configuration file or from the command line, operates 
much faster, and comes with a slew of other handy utilities 
for examining and manipulating object modules and libraries. 

The Tools 

There are five main tools in the LibTools toolchest: LIBMAN, 
L1BCOMP, L1BDUMP, MODLIST, and OBJREN. 

LIBMAN is the main library management tool. It cor¬ 
responds to LIB or TLIB, and you use it to create, add, edit, 
delete, update, and produce reports on libraries. Along with 
the operators that you would expect (+,-,*, ±, *- ) for ad¬ 
ding, deleting, and extracting object modules, LIBMAN supports 
wildcard file specifications and the ~ (tilde) update operator. 
LIBMAN can work entirely from the command line or can ac¬ 
cept a response file. 

I benchmarked LIBMAN vl.02 against Microsoft's LIB V3.14 
on an 80486DX, 33MHz computer using a 210Mb hard drive 
with 15.1ms average access time and a 569Kb/sec transfer 
speed. My disk cache was turned off. The test library was 
clipper.lib, which contained 206 object files (total size 
497,961 bytes). I used each library manager operation on 
three object files whose combined size was 57842 bytes. I 
used the command-line interface of both tools rather than a 
response file. Before each operation, 1 typed: 


copy clipper.lib test.lib 

so that each operation was done on a fresh, untouched copy 
of the test library. Figure 1 shows the result of my 
benchmark. My timings indicate that LIBMAN can be up to 
eleven times faster than LIB. 

L1BDUMP does what you might think: it dumps the informa¬ 
tion about the library or an object module in a library. It 
produces information on all of the segments, PUBLIC defini¬ 
tions, EXTERNAL references, memory model, and default 
libraries, in a convenient, easy-to-read format, shown in Figure 
2. This information can be extremely useful when, for ex¬ 
ample, you have compiled one module in a library with the 
wrong memory model and are getting segment fixup over¬ 
flows or duplicate symbols pulled in from two different 
memory model versions of the same runtime library. 

MODLIST lists the modules in a library. It is a quick way of 
checking what modules are in a library. As Figure 3 shows, 
MODLIST lists the internal module name, file name of the 
original source file with path and extension, and the date and 
time stamp of the module. 


Figure 1 Benchmarking LIBMAN versus LIB (times 
are in seconds) 
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Figure 2 LIBDUMP sample output 


LibTools -- Library Dump Tool : Version 1.03 

(C) Copyright 1992 Integrated Development Corporation. All Rights Reserved. 
THEADR : .\fileres.c 

LIBM0D : fileres 

Default Library : SLIBCE 
Processor : 8086 
Memory Model : Smal1 

SEGDEF : _TEXT 

SEGDEF : _DATA 

SEGDEF : CONST 

SEGDEF : _BSS 

Group : DGR0UP 
Segment : CONST 
Segment : _BSS 
Segment : _DATA 


EXTDEF 


VerifyFilename 

Type : 0 

EXTDEF 

GETFILERESOURCESIZE 

Type : 0 

EXTDEF 

GetResourceTableEntry Type : 0 

EXTDEF 

GETFILERESOURCE 

Type : 0 

EXTDEF 

ReadData 

FileHugeRead 

Type : 0 

Type : 0 

PUBDEF 

VerifyFilename 

Segment : _TEXT:146 

PUBDEF 

ReadData 

FileHugeRead 

Segment : TEXT:2a3 
Segment : _TEXT:2e8 


WORD PUBLIC Class 'CODE' Length:37e 
WORD PUBLIC Class 'DATA' Length:0 
WORD PUBLIC Class 'CONST' Length:0 
WORD PUBLIC Class 'BSS' Length:0 


THEADR : Afile.asm 

LIBMOD : file 

SEGDEF : TEXT 

SEGDEF : 'DATA 

Group : DGROUP 
Segment : _DATA 


WORD PUBLIC Class 'CODE' Length:76 
WORD PUBLIC Class 'DATA' Length:0 


PUBDEF 

FILEREAD 

FILESEEK 

FILEOPEN 

FILECLOSE 


Segment : _TEXT:31 
Segment : _TEXT:52 
Segment : _TEXT:0 
Segment : _TEXT:ld 
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LIBCOMP is a library comparison utility. It is used to deter¬ 
mine whether modules with the same name, in different 
libraries, are the same or different, it will also show if there 
are modules in one library which are not in another. Figure 4 
shows what LIBCOMP's output looks like. 

OBJREN allows you to modify the names of PUBLIC or EX¬ 
TERNAL symbols in single object modules (LIBMAN can change 
the public symbols and/or external references in an entire 
library file). This is a very powerful feature, but should be ap¬ 
proached with caution. You can use OBJREN to eliminate an 
unwanted external reference or to reduce executable size by 
eliminating unused routines. You can also use it to rename a 
PUBLIC symbol. If you wanted to write a substitute function 
to be used in place of a vendor-supplied library routine, you 
could rename the public symbol in the 
object module and supply your own. 

What OBJREN won't do is create a back¬ 
up copy of the library, or unmangle C++ 
symbols. 

You run all of the tools from a DOS 
command line. If you are using many 
options and parameters, you may want 
to use a configuration file called lib- 
tools.ini. libtools.ini is a Win- 
dows-style .ini file, and contains set¬ 
tings for file buffer sizes, module time 
stamping, module checksum verifica¬ 
tion, listing file options, and several 
“verbosity” settings which control how 


much information LIBMAN 
processing the library. 


gives you on screen while it’s 


The Documentation 

The manual thoroughly explains the circumstances under 
which you might want to change things, but the only thing I 
changed in the installation’s default .ini file was the listing 
file options. I told LIBMAN to always produce a group listing so 
that I could keep track of my default DGROUP growth. Other 
than that, the default . ini file worked well for all of my daily 
tasks. If I need to override a particular setting for any one 
session, I simply override the .ini file with a command-line 
switch. There's a corresponding command-line switch for each 


Windows Controls for C / Pascal ▼ ^ 

ensive Layout settings 

•• Arktext font and size (ATM, tt, system). 

® Text\nd background colors freely sel- 
I ectableX 

p> Unique Transparent Mode for static text 
fields. \ \ \ \ i 

o Vivid 3Q Appearance. 

3D depth and height freely adjustable. 



integrated Kolibri Resource Manager you 
can also develop extensive projects very 
quickly, and save on Windows System 
Resources. 


• Animated displays in buttons. 


User-defined bitmaps in all controls. 
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Occasionally, Windows/DOS 
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readers will find interesting. Cur¬ 
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Figure 3 MODLIST sample output 


Figure 4 LIBCOMP sample output 

LibTools -- Module List Tool : Version 1.02 


Comparison Listing -- 06-11-93 15:35:56 Page 1 

(C) Copyright 1992 Integrated Development Corporation. 


LibTools — Library Comparison Tool : Version 1.02 

All Rights Reserved. 


(C) Copyright 1992 Integrated Development Corporation. 

Opened : \clip501\lib\extend.lib 


All Rights Reserved. 

THEADR : X:\CC\MS\MISCX\GETE.C LIBM0D : GETE 


Source Library Name : dbfsix.LIB 

THEADR : X:\CC\MS\STR\PADR.C LIBM0D : PADR 


Target Library Name : clipper.LIB 

THEADR : X:\CC\MS\STR\PADC.C LIBM0D : PADC 


List File Name : CON 

THEADR : X:\CC\MS\STR\PAD.C LIBM0D : PAD 


sxtagin <— No matching module 

THEADR : X:\CC\MS\STR\IS.C LIBM0D : IS 


sxtagna <— No matching module 

THEADR : X:\CC\MS\STR\STRTRAN.C LIBM0D : STRTRAN 


esupport <— No matching module 

THEADR : X:\CC\MS\STR\EXAMPLEC.C LIBM0D : EXAMPLEC 


strnmat <— No matching module 

THEADR : X:\CC\MS\MEM0\HARDCR.C LIBM0D : HARDCR 


sxordclr <— No matching module 

THEADR : X:\CC\MS\EDIT\TBR0WSE0.C LIBM0D : TBR0WSE0 


dbcopy <— Different 

THEADR : X:\CC\MS\EDIT\TBR0WSE1.C LIBM0D : TBR0WSE1 


diskio4 <--- No matching module 

THEADR : X:\CC\MS\EDIT\ACH0ICE.C LIBM0D : ACH0TCE 


sxver <— No matching module 

THEADR : DIR LIBM0D : DIR 


Symbol : xpage update in diskio4 is duplicated in DISKI0 

THEADR : EXAMPLEP LIBM0D : EXAMPLEP 


Symbol : DBAPP in dbcopy is duplicated in DBCOPY 

THEADR : LBLRUN LIBM0D : LBLRUN 


Symbol : page readlock in diskio4 is duplicated in DISKI0 

THEADR : _TBR0WSE LIBM0D : _TBR0WSE 

Done... 


Symbol : _page_append in diskio4 is duplicated in DISKI0 


of the .ini file settings and the command-line overrides the 
. ini file. 

LibTools comes with a .ng help file which you can view 
with either the Norton Guide reader or Expert Help (a limited 
Expert Help is included; the full version is available from Sof- 
Solutions, 1-800-325-6820). There are also several tutorial files 
that will help you to understand all you need to know to 
begin using LibTools. Although the printed manual is not large, 
it discusses not only LibTools, but also libraries in general. I 
found it to be clear and very informative. 

Taken together, the .ng file, the tutorials, and the manual 
provide all the information you will need to manage your own 


libraries. If you need more help, excellent technical support is 
just a phone call away. In addition to 30 days of free 
telephone support and unlimited free CompuServe support, 
there’s also a 24-hour BBS where you can pick up the latest 
tips and download free patches to the latest version. 

Conclusion 

All in all, LibTools makes the critical job of library manage¬ 
ment quick, painless, and (almost) fun. Its speed, extensive 
reporting options, and strong technical support make it well 
worth the $149 price tag. A thirty-day money-back guarantee 
assures you'll be satisfied. □ 
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Lists and Database I/O 


This is the second in a series of columns about the design and implementation of 
WUIMAN (the Windows User Interface MANager). Last month’s column described the 
basic design of WUIMAN as a hierarchical tree of objects, each of which corresponds 
to a user interface element such as a window or menu. The hierarchical tree can 
also be viewed as a database; it provides persistence so that as the programmer or 
user interactively makes changes to the user interface, the corresponding changes in 
the WUIMAN database are remembered across invocations. I had intended to tackle 
the design and implementation of the WUIMAN database this month, but instead 
found it more convenient to get a couple more building blocks in place. 

.ini Files as Databases 

To store the WUIMAN database on disk, I needed some easy way to store hierar¬ 
chical information in a file. Windows does not supply any simple database 
functionality —or does it? It turns out that the Windows API for . ini files will work 
just dandy as a simple hierarchical database API, so long as the amount of data is 
not huge. An added benefit is that the WUIMAN database gets stored in simple text 
format that you can edit with any ASCII editor, rather than residing in some 
proprietary binary format that would require special software to examine or manipu¬ 
late. 


Ron Burk 


Ron Burk has a BSEE from the University of Kansas and has been a programmer for 
12 years. He is working on a book tentatively titled WinHelp for Programmers and 
Technical Writers. You may contact him at Burk Labs, P.O. Box 3082, Redmond, WA 
98073-3082. CIS: 70302,2566. BIX: rlburk; Internet: ronb@rdpub.com (". . . 

luunetlrdpublronb") 










A Windows . ini file contains a set of sections; within each 
section you can store one or more strings associated with 
values. Each section name must be distinct from all the other 
section names, and each string (but not value) within a sec¬ 
tion must usually be unique in that section. For example, a 
. ini file might look like this: 

[sectionl] 

Keyl=Valuel 

Key2=Valuel 

[section2] 

Keyl=Value2 
Key2=Value3 


where “[sectionl]" delimits a section named “sectionl”, “Keyl” 
is a section entry whose value is “Valuer, and so on. 

To map the WUIMAN hierarchical database onto a . ini file, 
I give each node in the hierarchy its own section and assign 
the section name based on the “path" to that node. Each at¬ 
tribute of a WUIMAN object gets stored with its value in the 
corresponding .ini section. The name of each child object 
also gets stored in the same section. I can prepend attribute 


Listing 1 wuidbint.h - Interface to database 
storage 


// wuidbint.h - WUIMAN DataBase INTerface declarations 

#ifndef WUIDBINT_H 
Idefine WUIDBINT_H 

#include <stdl ib.h> 

class TWuiDatabaseKeys; 
class TWuiDatabase 
{ 

public: 

TWuiDatabase(const char ‘Database); 

~TWuiDatabase(); 

int WriteItem(const char ‘Path, const char ‘Item, 

char ‘Data); 

int ReadItem(const char ‘Path, const char ‘Item, 

char ‘Buffer, size_t Length); 
TWuiDatabaseKeys ‘GetKeys(const char ‘Path); 
int DeleteItem(const char ‘Path, const char ‘Item); 

int DeletePath(const char ‘Path); 

private: 

char ‘DatabaseName_; 


class TWuiDatabaseKeys 
{ 

public: 

~TWuiDatabaseKeys(); 
const char ‘FirstKeyO; 
const char *NextKey(); 

private: 

friend TWuiDatabase; 

TWuiDatabaseKeys(char ‘Keys); 
char *Keys_; 

char ‘Current_; 

); 

#endif 

/* End of File */ 


names with a “." so that child object names do not conflict 
with attribute names in the same section. Figure 1 shows a 
fragment of a WUIMAN database, both as a tree and in a 
linear form as it might appear in a .ini file. Figure 1 fails to 
show that every WUIMAN database must start off with a root 
section (“[/]") that lists all the top-level objects in the database. 
From the root, you can traverse the entire hierarchy as you 
would any tree, but you have to maintain a path string to 
take you to the sections that correspond to the respective 
node in the tree. 

The only two functions required for creating and maintain¬ 
ing a .ini file are UritePrivateProfileStringO and Get- 
PrivateProfileString(). Flowever, I would like to avoid scat¬ 
tering calls to those functions throughout the WUIMAN code, 
in case I later want to store the WUIMAN database in some 
other format. Therefore, I created a class called TWuiman- 
Database to hide the details of file I/O. 

As usual, the price to pay for using the Windows API in¬ 
stead of rolling your own solution is that you have to put up 
with anomalies in Microsoft’s design. It should come as no 
surprise that the Windows . ini interface does not manage to 
handle NULL values uniformly. You cannot reliably use Get- 
PrivateProfileStringO to determine whether or not a sec¬ 
tion entry exists or not, since, if the entry does not exist, the 
function returns a default string that you must supply in the 
function call. The best you can do is pass in some bizarre 
default string such as “\xFF” that you believe will not arise in 
practice. Then, if GetPrivateProfileStringO returns the 
bizarre default string, you can hope (but not prove) it means 
that the corresponding entry did not exist. 

Another “helpful” feature in GetPrivateProfileStringO is 
that, if it discovers that the entry value begins and ends with 


Figure 1 Mapping a hierarchy to an .ini file 



.ini file 


[/Menu] 
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File= 

Edit= 

[/Menu/File] 
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single or double quotes, it strips off the quotes before return¬ 
ing. In addition to not being a minimalist, the designer of 
these functions was apparently not a mathematician, since 
this builtin feature creates a big singularity — GetPrivate- 
Profi leString() returns the exact string put there by Urite- 
PrivateProfileStringO, except for this special case. 

To work around both of these features, I append a sentinel 
character to all outgoing strings before calling UritePrivate- 
ProfileStringO and strip it off when I read strings back in 
from the .ini file. This means Windows will never see a 
string that begins and ends with a quote, so the quote-strip- 
ping feature is foiled. It also means that every string written 
to the .ini file is at least one character long (because of the 
sentinel character), so I can detect nonexistent entries by 
passing an empty default string and 
checking for a zero-length string. 

The class to hide the database I/O 
details, TUuiDatabase, is declared in 
wuidbint.h (Listing 1) and the im¬ 
plementation resides in wuidbint.c 
(Listing 2). An auxiliary class, TUui- 
DatabaseKeys, lets you obtain the 
names of all the items (children and at¬ 
tributes) that belong to a particular item 
in the database. This is necessary for 
traversing the database tree to load it 
and save it back to disk. These classes 
should be able to hide almost any im¬ 
plementation of the database, even if it 
were stored in something as ornate as 
an SQL server. 

Pointer Arrays 

Like a lot of programs, WUIMAN will 
have a need for variable-length lists of 
objects. For example, each node in the 
database can have zero or more child 
nodes and zero or more attributes. Both 
of these can be represented by arrays 
of pointers to objects, so I will use a 
general-purpose pointer array class to 
handle both children and attributes. The 
class I created, called TUuiGenericList, 
is in wuilist.h (Listing 3). The code to 
implement TWuiGenericList is in 
wuilist.c (Listing 4). This class 
manages void pointer arrays, so l will 
make wrapper classes that supply the 
appropriate casts to and from void * 
to create lists of specific classes of ob¬ 
jects. This is a perfect application for 
C++ templates, since you can create a 
single template that can instantiate 
these sorts of wrapper classes with a 
simple declaration. However, I am trying 
to keep the code compatible with 
Microsoft Visual C++, which does not 
support templates. 


Creating a general-purpose list class sounds like a perfect 
first exercise for a beginning C++ programmer. In fact, trying to 
do the job well is a good exercise for an experienced 
programmer, as it raises a variety of class design issues. For 
example, will your list store objects (value semantics) or 
pointers to objects (reference semantics)? How will the user 
iterate over the objects in the list? Will iteration still work (or 
at least not crash) if the user deletes elements from the list 
while iterating over it? 

TWuiGenericList is far from general-purpose; I haven’t had 
much success creating a list class I care to reuse in all cir¬ 
cumstances. I have, however gotten a lot of reusability at the 
source code level — TWuiGenericList is cannibalized from a 
simple list class I was using in another project. Unlike the class 
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it came from, however, TUuiGenericList treats adding a NULL 
pointer as an error. TUuiGenericList numbers its elements 
from zero, and you specify an offset (just like an array) to 
obtain a particular element from the list. TUuiGenericList 


grows dynamically as you add more elements. It lets you in¬ 
sert new elements at a specific position in the list (in case you 
need an order-dependent list), but also makes it easy to just 
append the new object to the end of the list. 


Listing 2 wuidbintc - .ini implementation of storage 


II wuidbint.c - WUIMAN DataBase INTerface definitions 


#include <string.h> 

// DeletePath - Delete path itself (and any children) 
int TWuiDatabase::DeletePath(const char ‘Path) 

#include "wuistd.h" 

{ MEMBERASSERTO; 

return WritePrivateProfileString(Path, NULL, NULL, 

finclude "wuidbint.h" 

DatabaseName_) != 0; 

#if ! (defined ( INC WINDOWS) || defined( WINDOWS H)) 

/ 

finclude <windows.h> 

// GetKeys - Get the children/attribute of specified path. 

#endif 

TWuiDatabaseKeys ‘TWuiDatabase::GetKeys(const char ‘Path) 

const char ‘SENTINEL = 

{ MEMBERASSERTO; 

const int MAXKEYS = (1024*4); 


char ‘Keys = new char[MAXKEYS]; 

// constructor - just save database name (assume it's legal) 


TWuiDatabase::TWuiDatabase(const char ‘Database) 

// if no keys found, or too many to fit in buffer, 

: DatabaseName (StringClone(Database)) 

// then fail by returning 0. 

( MEMBERASSERTO; 


) 

int Status = ReadItem(Path, NULL, Keys, MAXKEYS); 

// destructor - free up database name 

if(Status <= 0 || (Status >= MAXKEYS-1) ) 

{ 

TWuiDatabase::~TWuiDatabase() 

del ete [] Keys; 

( MEMBERASSERTO; 

return 0; 

if(DatabaseName ) 

) 

delete[] DatabaseName ; 

el se 

} 

return new TWuiDatabaseKeys(Keys); 

} 

// Writeltem - Set value for item under specified path. 

int TWuiDatabase::WriteItem(const char ‘Path, 

// constructor - Save string of keys. 

const char ‘Key, char ‘Buffer) 

TWuiDatabaseKeys::TWuiDatabaseKeys(char ‘Keys) 

{ MEMBERASSERTO; 

: Keys (Keys), Current (Keys) 

char ‘Copy = new char[strlen(Buffer)+2] ; 

{ MEMBERASSERTO; 

strcpy(Copy, Buffer); 

ASSERT(Keys != 0); 

strcat(Copy, SENTINEL); 

) 

int Status = WritePrivateProfileString(Path, Key, Copy, 


DatabaseName ) != 0; 

// destructor - Free string of keys. 

delete [] Copy; 

TWuiDatabaseKeys : :~TWuiDatabaseKeys () 

return Status; 

{ MEMBERASSERTO; 

) 

if(Keys ) 

// Readltem - Get value for named item under specified path. 

del ete [] Keys ; 

) 

int TWuiDatabase::ReadItem(const char ‘Path, 


const char ‘Key, char ‘Buffer, size t Length) 

// FirstKey - fetch first key of series. 

{ MEMBERASSERTO; 

const char ‘TWuiDatabaseKeys::FirstKey() 

char ‘Copy = new char[Length+2] ; 

( MEMBERASSERTO; 

int Status * GetPrivateProfileString(Path, Key, 

return Current = Keys ; 

Copy, Length, DatabaseName ); 

i 

if(Status <= 0) 


Status * -1; 

// NextKey - fetch next key in series, NULL if at end. 

el se 

const char *TWuiDatabaseKeys :: NextKey () 

( 

( MEMBERASSERTO; 

ASSERT(Copy[str1en(Copy)-l] == SENTINELfO] ); 

ASSERT(Current != NULL); 

Status = strlen(Copy)-l; 

if(‘Current ) 

Copy[Status] = ' \0 '; // trim sentinel byte before 

Current += strlen(Current )+l; 

returning 

return Current ; 

strcpy(Buffer, Copy); 

i 

) 

del ete [] Copy; 

/* End of File */ 

return Status; 

) 

// Deleteltem - Delete named item under specified path, 
int TWuiDatabase::DeleteItem(const char ‘Path, 

const char ‘Key) 

{ MEMBERASSERTO; 

return WritePrivateProfileString(Path, Key, NULL, 

DatabaseName ) != 0; 

} 
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With this month’s code in place, i should finally be able to 
present the base class that defines the behavior of WUIMAN 
user interface objects next month. 

Bug++ of the Month 

My nomination for the meanest, nastiest PC C++ bug goes 
to Borland C++ v3.1, and it isn’t even in their compiler. I use 
their command-line compiler inside a DOS box to compile and 
link my program, then switch back to Windows to test it. 
After an hour or two of this, sooner or later I forget to ter¬ 
minate the application before returning to the DOS box to 
make more changes. Then, when Borland C++ hits the link 
phase, I get a file-sharing error because the linker tries to 
write on the . exe that is still executing. 

I don’t know about you, but when I see an “Abort, Retry, 
Fail?’’ message, I hit the "A” key reflexively. Unfortunately, in 
the situation just described, the result is a hung DOS box. Only 
if I remember to bang on the “F” key instead can I save the 
session. You might think I could terminate the DOS box (ignor¬ 
ing the ominous warnings associated with that dialog box op¬ 
tion), start it up again, and be on my way. Not so, because 


Listing 3 wuilist.h — Declaration of simple object 
list class 


II wuilist.h - WUIMAN generic list class 

#ifndef WUILIST_H 
#define WUILIST_H 

#include "wuistd.h" 

class TWuiGenericList 
{ 

public: 

TWuiGenericList(int Initial Size = 0); 
TWuiGenericList(const TWuiGenericList&); 
void operator=(const TWuiGenericList&); 
~TWuiGenericList(); 
void *Get(int Index); 
void *Remove(int Index); 
void *Insert(void *Addition, int Index=-1); 
int NElements(); 

private: 

void SetSize(int NewSize, 

const TWuiGenericList &0ther); 

void **List_; 
int ListSize_; 

int NElements_; 

); 

inline 

int TWuiGenericList::NElements() 

( MEMBERASSERT(); 
return NElements_; 

) 

inline 

void ‘TWuiGenericList::Get(int Index) 

{ MEMBERASSERT(); 

ASSERT(Index < NElements_ && Index >» 0); 
return List_[Index]; 

) 

#endif 

/* End of File */ 
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then I get a file-sharing error on Borland’s make.exe, which is 
probably still being held open by the dead DOS box. If I had to 
choose whether the next Borland C++ would implement ex¬ 
ceptions or fix this bug, I’m afraid I’d have to pick fixing the 


bug. After all, I don’t know for sure that exceptions will make 
me more productive, but fixing this bug definitely would I In¬ 
cidentally, both Microsoft and Zortech linkers just terminate 
with an error message in this situation, as one would hope. □ 


Listing 4 wuilist.c - Implementation of simple object list class 


II wuilist.c - WUIMAN generic list classes 

#include <string.h> // memcpyf) 

#include "wuilist.h" 

TWuiGenericList::TWuiGenericList(int Initial Size) 

: List_(0), ListSize_(0), NElements_(0) 

{ MEMBERASSERTQ; 
if(InitialSize > 0) 

SetSizeQnitialSize, ‘this); 

I 

// copy constructor 

TWuiGenericList::TWuiGenericLi st( 

const TWuiGenericList& Other) 

: Li st_(0) 

{ MEMBERASSERTQ; 

♦this = Other; // pass the buck to assignment op 


// assignment operator - pass buck to SetSizeQ 
void TWuiGenericList::operator=( 

const TWuiGenericList& Other) 

{ MEMBERASSERTQ; 

if(this 1= &0ther) // detect self-assignment 
SetSize(Other.NElements_, Other); 

) 


// destructor - free up memory 
TWuiGenericList::~TWuiGenericList() 

{ MEMBERASSERTQ; 
if(List_) 

delete[] List_; 

) 

// SetSize - handle growing, shrinking, copying. 

// Note: Other could be me! 

void TWuiGenericList::SetSize(int NewSize, 

const TWuiGenericList iOther) 

{ MEMBERASSERTQ; 

int CopySize ■ (NewSize < Other.NE1 ements_) 

? NewSize : Other.NElements_; 

void **NewList = 0; 
if(NewSize > 0) 

{ 

NewList = new void ‘[NewSize]; 

ASSERT(NewList 1= 0); 
if(Other.List_ 1= 0) 

memcpy(NewList, Other.List_, sizeof(void*)‘CopySize); 
if(List_) 

deleteQ List_; 

List_ = NewList; 

I 

else 


NEW! 
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List_ * 0; 

ListSize_ = NewSize; 

} 


II Insert - add object at specific position 
void ‘TWuiGenericList::Insert(void ‘NewObject, int Position) 
{ MEMBERASSERTQ; 

ASSERT(NewObject 1= 0); 

if(Position < 0 || Position > NElements_) 

Position = NElements_; // default is append 
if(ListSize_ *» NElements_) 

SetSize(NE1ements_+l, ‘this); 
if(Position 1= NElements_) 

memmove(&List_[Position+l], &List_[Position], 

sizeof(List_[0]) * (NElements_-Position)); 
List_[Position] = NewObject; 

++NElements_; 

ASSERT(NElements_ <= ListSize_); 
return NewObject; 

} 

// Remove - Remove object at specific position. 

// Note: RemoveQ does not delete object for you. 

void ‘TWuiGenericList::Remove(int Position) 

( MEMBERASSERTQ; 
void ‘Removed = 0; 

if(NElements_) // if we have any to delete 

I 

// default is to delete last element of array 
if(Position < 0 || Position >= NElements_) 

Position = NElements_-l; 

Removed = List_[Position]; 

—NE1ements_; 
if(Position < NElements_) 

memmove(&List_[Position], &List_[Position+l], 
sizeof(List_[0]) * (NElements_-Position)); 

} 

return Removed; 

) 

/* End of File */ 
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Paul Bonneau 


Send questions to Paul via Internet 
as paul@rdpub.com-, 
from CompuServe: 

> INTERNET:paul@rdpub. com-, 
or in care of this magazine at: 

1601 W. 23rd St., Suite 200 
Lawrence, KS 66046-2743. 


Q I am writing a program that needs to draw on screen when an interrupt oc¬ 
curs. But this will cause problems when other applications are doing their own 
painting for example, when they are processing their own WM_PAINT messages. I 
doubt whether GDI is reentrant. 

I could just use PostMessage() to post a message to my window procedure, but 
this is not good since the message would be queued. What I need is to respond 
immediately by drawing on the screen even when a window is processing a mes¬ 
sage. 

Tsing-Fan Lin 
Computer Center 
Dept of Computer Science & Information Eng. 
National Chiao-Tung Univ., Hsin-chu 

Taiwan 

tflin@pinton.csie.nctu.edu.tw 

A Unfortunately, you have encountered a fundamental limitation of Windows 3.1. 

It is non-preemptive and, except in certain circumstances, non-reentrant. Unlike 
traditional operating systems, such as UNIX, most of the Windows API is not safe to 
call while processing an interrupt; the only API function that Microsoft officially sanc¬ 
tions calling at interrupt time is PostMessage(). There are other API functions that 
may be called safely in Windows 3.1, but Microsoft does not guarantee this behavior 
in future versions of Windows. 

The cases where Windows is reentrant occur in the handling of messages. A 
prime example is DefWindowProc(). Since most windows functions call DefUindow- 
Proc() to provide default handling of messages, there are many cases where it will 
be reentered, because handling a message for a window frequently results in the 
sending of other messages for the same window. In these cases, Windows has 
presumably been designed to handle the reentrant call safely, although there are 
instances where this is not true (under Windows 3.0 TranslateAccelerator() is not 
reentrant, even though it generates messages-, I don’t know if the problem has been 
corrected in 3.1). 

If you truly must update the screen at interrupt time, then to be robust you 
must do so without using the Windows API, which implies writing directly to video 
memory. This is not a particularly attractive option because it ties you to a specific 
device, causing you to lose the device independence provided by Windows. Depend¬ 
ing on the frequency of your interrupts, real-time painting may not even be possible 
with direct screen writes. The latency in receiving an interrupt from an interrupt 
handler in a windows program or DLL under enhanced mode is large (especially if 
one or more DOS boxes are present), on the order of hundreds of microseconds or 
even milliseconds. If you then add the time required to update a significant portion 
of the display (another slow operation), depending on the display device, you may 
be able to handle only a few interrupts per second or less. 


Paul Bonneau is a Software Design Engineer at a major software firm. He was a 
developer of HyperChem, a molecular modeling system marketed by Autodesk. 























Listing 1 notify, h — Headerfilefornotify.dll 



/* notify.h */ 

/* — Interface to notify dll. */ 


typedef struct _0FI 
( 

WORD pdb; 
int wHandle; 

char szPath[124]; /* Make Struct size 2*x. */ 

} OFI; /* Open file info. */ 

void WINAPI _export SetPostWnd(HWND); 

BOOL WINAPI _export FNextOfi(OFI far \ long far *); 

/* End of File */ 


You might consider the possibility of writing your applica¬ 
tion to use a non-yielding PeekMessagef) loop in conjunction 
with calling PostMessage() from the interrupt handler. By 
passing the PM_NOYIELD flag to PeekMessage(), your applica¬ 
tion will always be in control of the processor, ensuring the 
quickest possible receipt of the posted message. The draw¬ 
back is that other applications will not get a chance to run 
while your application is in the non-yielding loop. 


ADVANCED 
SOLUTIONS 
FOR C/C++ 
PROGRAMMERS 


Q I have a question that perhaps you can answer. I am 
currently trying to create an application in Microsoft 
Windows that can display each of the programs currently run¬ 
ning and the files that each of these programs has open. My 
current approach is to walk the task list 
and obtain a selector for the PSP (ex¬ 
cuse me, PDB) for each task. From the 
PDB, I can obtain the handles for every 
file that the task has open. I am stumped, 
however, because I can't find a way to 
get a file name from a file handle. Is there 
a way to do this? Is there a better way to 
solve my problem? 

Jo Fisher 
CompuServe: 74200,351 


If you program in C/C++ you need the 
solution-oriented information found only 
in The C Users Journal. We devote 12 
issues every year to the language of 
choice, C/C+ + . Each issue is crammed 
with information on ANSI C, C+ + , 
debugging, tutorials, code, and more. 

A FREE issue of The C Users Journal 

is yours-call now and ask for a trial 
subscription. If you like the code-inten¬ 
sive C/C+ + programming solutions you 
find in your FREE issue, pay only $29.95 
for a full year’s subscription. If not, write 
‘cancel’ on the accompanied invoice 
and owe nothing. There’s NO RISK and 
NO OBLIGATION. 


Try a 

FREE ISSUE 


The 




Users Journal 


tm 


1601 West 23rd Street, Suite 200 
Lawrence, KS 66046 USA 


CALL: 913-841-1631 
FAX: 913-841-2624 


Non U.S. orders must prepay ($46 Canada/Mexico, $65 outside North America) in U.S. funds. 


A Well, I do have an answer for your 
problem, but I don't know how 
you’ll like it. It seems that many of the 
questions I am asked can only be 
answered by exploiting various undocu¬ 
mented or version-dependent features 
of Windows, but my answer for yours 
reaches a record high on the sleaze-o- 
meter. (There seems to be a correlation 
between the number of open books 
and magazines strewn about the floor 
by the time I have finished coding an 
answer with the overall nastiness of the 
code; after your question, I can barely 
see my floor.) If you are writing a 
debugging tool, the technique I am 
about to present should be useful, but 
it is not suitable for most commercial 
software (it is highly dependent on the 
version of Windows running). 

Using the PDB 

My first attempt (one of many!) at 
answering your question was to take a 
look at the file handles stored in a 
task’s PDB (the protected-mode version 
of a PSP, embedded in the task 
database, the TDB, at offset 0x100. 
There were two interesting anomalies. 
First, the open file handles in the PDB 
do not correspond to the file handles 
returned from the corresponding file 
open calls, and second, the file handles 
held open by KERNEL were nowhere to 
be found. KERNEL has to open files 
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(such as module files), but I could not locate the PDB contain¬ 
ing the handles for these open files. Another interesting fact is 
that the file handles (except for the first five, which are always 
redirected to [1, 1, 1, 0, 2]) are all unique. This seems to indi¬ 
cate that they reference individual entries in a global DOS Sys¬ 
tem File Table (see Jeff Prosise’s MS-DOS Q6cA column in the 
August 1993 Microsoft Systems Journal, page 79, for a good 
discussion of the DOS SFT and how to obtain a filename from 
a file handle in DOS). However, using a global DOS SFT does not 
explain the lack of the file handles held open by the system, 
such as module files. This made me think it might be better 
to trap the INT 0x21 calls used to manipulate file handles and 
maintain a list. In other words, I would intercept calls to INT 
0x21 and, when the call was a file open, add the filename to 
a list and then remove it when a corresponding file close in¬ 
terrupt arrived. 

Intercepting INT 0x21 

Intercepting INT 0x21 was my second failed attempt to 
answer your question. It turns out that Windows provides a 
protected-mode version of the INT 0x21 handler that lives in 
a fixed KERNEL code segment (you can obtain the address of 
an interrupt service routine using the WDEB396 “di" command, 
or the Soft-ICE/W “idt” command). Not only does Windows 
provide protected-mode versions of the file handle services, 
but it also provides its own versions of the get and set inter¬ 
rupt vector services as well. So it seemed straightforward to 
write a DLL to intercept INT 0x21 by chaining. I chose to use 
a DLL, since the intercept code needs to be fixed, but in 
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Figure 1 Patching a reentrant function 
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theory I could have placed it in a task. As it turns out, only a 
DLL will work (I’ll get to the reason why in a bit). 

One of the problems with hooking a function called at in¬ 
terrupt time is the extremely limited set of Windows API func¬ 
tions you can call from within an interrupt service routine 
(ISR). This means that the intercept routine cannot dynamically 
grow its list as new files are opened. Therefore ISRs are typi¬ 
cally implemented in two halves (see the article “Embedded 
Device Drivers Simplify the Support of Unusual Devices under 
Windows” by Gordon S. Smith in the May-June 1991 issue of 
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Microsoft Systems Journal): the bottom half is the actual ISR 
that buffers data, and the top half is called by a client task to 
remove data from the buffer. The top half is not called at 
interrupt time, so it has access to the full Windows API. 

My idea is similar. The DLL acts as the bottom half, and a 
client task, responsible for displaying the results, acts as the 
top half. The DLL preallocates space for some number of 
entries, and fills this buffer from its intercept routine. When 
the client calls the DLL to ask for entries, the DLL grows the 


size of the list if it is within a constant threshold of being full. 
This way, unless a process opens a large number of files 
without yielding, the DLL can maintain a very large list of open 
files. Since it is legal to call PostMessagef) at interrupt time, 
the client task registers itself with the DLL by providing a win¬ 
dow handle to post messages to. Each time the list is 
changed, a private message is posted to the client. When the 
client receives the message (I chose MM_USER), it calls back to 
the DLL to obtain the list, giving the DLL its chance to grow 


Listing 2 notify.c - Source code for DLL to intercept INT 0x21 

j*****************************************************i 

j*****************************************************j 

/* notify.c */ 

/* -- Called at load time. */ 

/* -- DLL tracks open files by hooking int 21 */ 

/* -- Install the int 21 ISR hook, save the old */ 

/* functions */ 

/* contents. */ 

/* — To build: */ 

!*****************************************************i 

/* cc -wd -DSTRICT notify.c libentry.obj \ */ 

( 

/* toolhelp.lib */ 

/* implib notify.lib notify.dll */ 

BYTE rgbJump[5]; /* Far jump to our hook. */ 

J*****************************************************j 

/* Preallocate some space for the file list. */ 

linclude <windows.h> 

if ((gprgofi = GlobalAllocPtr(GMEM SHARE | 

linclude <windowsx.h> 

GMEM MOVEABLE | GMEM ZEROINIT, 

linclude <toolhelp.h> 

dcofi * sizeof(OFI))) «« NULL) 

linclude "notify.h" 

return FALSE; /* No memory. */ 

typedef struct 

cofi = dcofi; 

f 

UINT wES, wDS, wDI, wSI, wBP, wSP, wBX, wDX, 

cofiUsed » 0; 

wCX, WAX, wIPReturn, wCSReturn, wFlagReg; 

/* Find and read the int 21 ISR. */ 

} REG; /* interrupt routine stack. */ 

asm mov ax, 3521h 


asm int 21h 

/* Increment this many file info entries at a time. */ 

asm mov wOff, bx 

Idefine dcofi 100 

/* Get more space when number of free entries hits */ 

asm mov wSel, es 

MemoryRead(wSel, wOff, rgbSav, sizeof rgbSav); 

/* this value. */ 

/* Replace first 5 bytes with jump to hook func. */ 

Idefine cofiLow 50 

rgbJump[0] = Oxea; 

‘(DWORD *) (rgbJump + 1) = (DW0RD)Hook21; 

/* Internal prototypes. */ 

MemoryWrite(wSel, wOff, rgbJump, sizeof rgbJump); 

void CopyLpsz(LPSTR, LPSTR) ; 

return TRUE; 

WORD PdbGetCur(void) ; 

OEI far * LpofiFind(int) ; 

) 

void Notify(void) ; 

lifdef BORLANDC 

void NotifyClose(int); 

Ipragma argsused 

void NotifyDuplicate(int, int); 

lendif 

void NotifyOpen(LPSTR, int); 

int CALLBACK export WEP(int wExitCode) 
^***************************************************** ^ 

/* Exported prototypes. */ 

/* — Remove the int 21 ISR hook. */ 

lifdef BORLANDC 

/* — No need to explicitly free file list, since */ 

void interrupt export Hook21(REG); 

/* its done for us by Windows. */ 

lelse 

j ******★★★★★***★****★*****************★★*★*★★★★*★★★*★* J 

void interrupt export cdecl Hook21(REG); 

{ 

lendif 

MemoryWrite(wSel, wOff, rgbSav, sizeof rgbSav); 
return 1; 

int CALLBACK LibMain(HINSTANCE, WORD, WORD, LPSTR); 
int CALLBACK _export WEP(int); 

) 

lifdef BORLANDC 

HWND hwndNotify; /* Notify when list changes. */ 

void interrupt export 

OFI huge * gprgofi ; /* File info list. */ 

lelse 

long cofi; /* Size of list. */ 

void interrupt export cdecl 

long cofiUsed; /* Number of files in list. */ 

lendif 

BOOL fNotified; /* Client has been notified. */ 

Hook21(REG reg) 

BYTE rgbSav[5] ; /* Start of int 21 ISR. */ 

/***************************************************** j 

WORD wSel ; /* Selector:offset of */ 

/* — Int 21 ISR hook. */ 

UINT wOff; /* original int 21 ISR. */ 

^*****************************************************j 

lifdef BORLANDC 

\ 

UINT wFunction = reg.wAX & OxffOO; 

Ipragma argsused 

FARPROC lpfn = MAKELP(wSel, wOff + 6); 

lendif 

int CALLBACK 

WORD wSelPriv; 

LibMain(HINSTANCE hinsThis, WORD ds, WORD cbHeap, 

/* Hack-o-rama. I have embedded a routine that */ 

LPSTR lpsz) 

/* replicates the results of the first 2 */ 

/* instructions of the ISR: */ 
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C CODE FOR THE PC 

source code, of course 

X/DOS and Xt/DOS (Xlib with X client and Xt toolkit for DOS; port X code to DOS; Xl/DOS require* X/DOS and 32-bit compiler) . . each $345 
ZIP Image Proceiaor A Victor Image Library Version 2.2 (brightness, contrast, merge images, TIIT/GIF/PCX/bin, HP ScanJet support) . . $290 

The Snooper (Ethernet protocol analyzer for Novell NetWare and LAN Manager Networks; capture packets; real-time display).$275 

Embedded BIOS (full-featured, real-time input/output system; PC, XT AT) for example, 80186 with 8259 interrupt controller).$260 

C/C+ + Libraries by Code Farms (persistent C structures, ER models, dynamic arrays, database functions. Jolt Award winner).$250 

Tlirbo’IfcX (Release 3.0; HP, PS, dc* drivers; CM fonts; Lal^X; MetaFont).$250 

Rogue Wive tool*.h+-f- or math.h+-f- Class Library (extensive docs)..each $240 

c-palib (PostScript generation library for C programs; includes complete graphics, font, rotation & paragraph support).$170 

COMM-DRV (complete interrupt-driven serial communication libraries A device driven; full source). $155 

TE Editor Developer’s Kit Ver. 3.0 (full screen editor, undo command, multiple windows; with Word Processing $230).$155 

Mi nix Operating System (Version 1-5; Unix-like operating system, includes manual; 3-5” diskettes only).$150 

Ddorie GCC for MS-DOS (Version 2.2.2; includes C++, assembler, DOS extender, 387 emulation; complete source code and makefiles) . . $150 

I brow (Version 4.1; programmer’s Windows-based editor, large files, help, undo/redo, drag-n-drop, function & type tags).$135 

Booter Ibolkit (floppy disk bootstrap routines, DOS file system, light-weight multitasking, windows, fast memory management) .$120 

Lisp for DOS (Kyoto Common Lisp and CLISP; KCL includes Lisp-to-C translator for building mixed Lisp/C programs).$100 

386BSD Version 0.1 A LINUX Version 0.96 (two Unix clones for Intel 386) .$100 

PC/IP (CMU/MIT TCP/IP for PCs; Crynwr drivers, NFS server, Bdaie mailer, PCRoute/PCBridge, NDIS/ODI drivers, Beholder, more) . . . $100 

Demacs (complete GNU Emacs for DOS; needs djgcc to build; based on 18.55).$100 

DA (disassembler for Microsoft’s New Executable (NE) binary files including Windows exe, ,drv, .dll, and .fit).$95 

Script Interpreter (a command script interpreter for DOS-based systems; C-ukc script language; lots of features).$90 

HorC++ Power (C+ + Class Library for Borland’s Paradox Engine).$80 

CELP 3.2c (Federal Standard 1016 Code Excited Linear Predictive voice sampling and encoding; voice over 4.8kbps).$80 

CPPCOMM (Version 3.0; C++ serial communications class library for DOS, Windows, OS/2, and NT, includes X/Y/Zmodem) .$75 

ET Neural Net (back error propagation and Kohonen; specify DOS text, DOS VGS, or Windows).$75 

FlexList (doubly-linked lists of arbitrary data with multiple access methods; specify Cor C++).$65 

Smalltalk for DOS (port of GNU Smalltalk using djgcc).$60 

Kier DateLib (all kinds of date manipulation; translation, validation, formatting, A arithmetic).$60 

Co der's Prolog (Version 3.0; inference engine for use with C programs).$60 

PCCTS (Purdue Compiler Construction Tool Set; ported to Microsoft C; like YACC and LEX together with lota of additional features) . . . $60 
MEM.WING (global memory manager for Windows, supports standard C memory allocation calls to "wing" your old C code into Windows) . $55 

Container Lite V 1.82 (C+ + A FLC wrapper emulators; portable, persistent containers of arbitrary data including pointers).$50 

BigFloat (arbitrary precision floating point arithmetic and functions; includes BCD conversion).$50 

EZCalc (ASCII algebraic expression evaluator, unlimited parenthesis nesting, symbols, 32 built-in functions, easily extended).$50 

Backup & Restore Utility by Blake McBride (multiple volumes, file compression & encryption).$50 

SuperGrep (exceptionally fast, revolutionary text searching algorithm; also searches subdirectories).$50 

Moby Crypto (Volume 1: DES, Lucifer, SRNG, ARNG; Volume 2: PGP, RSA, MD4, SHA; both volumes $75; not for export).each $50 

OBIASM (convert .obi files to .asm files; output is MASM compatible) .$50 

NIH Class Library & Book (basic C++ classes A Data Abstraction and Objcct Orimai Prog-ammingm C+ + in softback by Keith Gotien) $50 

Editor Pack (20 public domain editors; micromacs 3.12, Stevie, Elvis, Moke, mg2a, DTE, Jcwe, Origami, CE A GRIEF).$50 

MicroC C Compiler (retargetable C compiler/optimizer, lots of docs, very portable, 8086 tables included; tables for 7 extra epu’s $50) .... $50 

Exceptions for C (Ada-like exception handling for C programs; exceptions for any block; exceptions can be reraised).$45 

TOUR (beautiful traveling salesman problem solver, finds minimum length paths quickly, includes graphics & plotting programs) .$40 

DES Encryption A Decryption (2500 bits/second on 4.77 MHz PC for on-the-fly encrypuon at 2400 baud; not for export).$40 

Database Pack (9 databases - simple to complex: isam, bplus, AVL, SDB, ID, gdbtn, Requiem, Ingres89, Postgres).$35 

COP (poor man’s C++; C macro package which implements C+ + in C) .$35 

RXC A EGREP Version 2.0 (Regular Expression Compiler and Pattern Matching; finite state machine from regular expression).$35 

Bison A BYACC (YACC workable parser generators; documentation; includes C and C++ gramman) .$35 

Spell Pack (6 spelling programs, a hyphenator, 2 utility packs and a 60K word list: Ispell, Microsp, Sp, Cspella, Spell, Dawg, Soundex) .... $30 

AUoc-GC (a garbage-collecting memory allocation library).$30 

REGX Plus (Version 3.0, search and replace string manipulation routines based on compiled regular expressions).$30 

GNU Awk A Diff for PC (both programs in one package).$30 

Big Number Pack (7 arbitrary precision arithmetic packages in C, one in Fortran but free Fortran-to-C converter is included) .$30 

Crunch Pack (30 file compression A expansion programs; now includes portable ZIP).$30 

OEmacs (full GNU Emacs for DOS and Windows DOS box; C+ + support, etags++, low of .el files) .$25 

UUPC Pack (UUCP for the PQ UUPC Version 1.11V, smail & snews) .$25 

PERL for MS-DOS (Version 4.019; C, sed, awk, and shell all rolled into one language; includes hardcopy docs).$25 

FLEX (fast lexical analyzer generator; new, improved LEX; BSD Version 2.3.6 with docs).$25 

GNU RCS (FSFs version of the Revision Control System; like Unix’s SCCS only better, Keeps track of software development).$20 

Simple Socket Library (Unix, VMS and MS-DOS; sits on TCP/IP stack).$20 

Bywater BASIC Version 1.10 (complete BASIC interpreter and interactive programming environment).$20 

Data 

Moby Thesaurus (25K root words, 1.2M synonyms).$350 

Moby Part-of-Speech (200,000 words and phrases described by prioritized part(s)-of-speech).$120 

Moby Words (500,000 words A phrases, 9,000 stars, 15,000 names).$80 

Dictionary Word List (234,932 words in alphabetical order).$60 

Roget’s 1911 Thesaurus.$40 

U. S. Cities (names A longitude/latitude of 32,000 U.S. cities and 6,000 state boundary points).$35 

CIA World Bank II Database (13MB of maps, 5.7M vectors; coastlines, rivers, political bounaaries; Africa, Asia, Europe, N. & S. America) $35 

The World Digitized (100,000 longitude/latitude of world country boundaries).$30 

Lou ’O Words (160,066 German, 178,430 Dutch, 61,843 Norwegian, 60,453 Italian, 138,257 French, 53,142 English).$30 

CD-ROMs 

FontMaster Library (soft fonts for HP and HP compatible laser printers, 36 different type faces; 5,200 bit mapped fonts; 300MB).$70 

Prime Time Freeware for Unix (Volume 2, No. 2, July, 1993; over 3.5GB of Unix C code).$60 

Whlnut Creek Libris Britannia (over 600MB of the best of British boards; not all source included).$55 

Lirfux/GNU/X by Yggdrasil Computing (1st production release; run from the CD; TCP/IP A NFS; drivers; MPEG; SCSI support; lots more) . $45 

Knowledge Medai Multimedia (625MB & 13,000 files; 1,232 sounds, 179 books, 100 movies, 114 stacks, 606 programs, 214 mods) .$40 

Vfelnut Creek C User’s Group (Volumes 100 to 364).$40 

InfoMagic Unix (three public domain Unix systems: 386BSD (version 0.1), Linux (version 0.99.10), and NetBSD).$40 

InfoMagic Source Code (Berkeley Net/2, MACH, GNU, Interviews, X, Andrew, XFrce, Demacs A Winemacs, djgpp, Modula-3, etc.) . . . $40 
Knowledge Media Languages A Operating Systems (640MB of compilers, libraries, and operating systems; source code A executables) . . . $35 

Walnut Creek X11R5 and GNU (X11R5 with contributed and compsourcesx, over 120 GNU programs, complete C source).$35 

Wdnut Creek Usenet and Simtel Unix-C (600MB).$35 

Austin Code Works Internet Warrior #1 (PC Internet tools: Gopher, Wiis, Eudora, ph, Nupop, Thun pet, TCP/IP, FAQs, drivers, docs) . . . $35 

Wdnut Creek Simtel 20 MSDOS Archive (C source code but lou of other stuff too).$20 

Sprite Network Operating System (source code A documentation of Ousterhout’s Sprite O/S; Sun and DECStation boot images).$20 

The Austin Code Works Voice: (512) 258-0785 

11100 Leafwood Lane much more ... ask for catalog FAX: (512) 258-1842 

Austin, Texas 78750-8587 USA E-mail: info@acw.com 

Free surface shipping for cash in advance For delivery in Texas add 7% MasterCard/VISA 
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the list if necessary. I created a listbox in the client to display 
the list of open files. 

The sooner the client task and DLL run after system startup 
the better, since this will yield a more accurate list. Ideally, 
the client task should even run before Program Manager runs, 
so that it can display any files opened by Program Manager or 
by applications that Program Manager automatically starts. It 


is possible to change the “shell-’ line in system, ini to invoke 
a program other than Program Manager as the first to run at 
startup. I decided to exploit this functionality by designing the 
client task, filelist.exe, to act as a minimal shell that invokes 
Program Manager by calling UinExec() during initialization. 

The DLL, notify.dll, stores the original ISR in LibMain() 
using I NT 0x21, function 0x35. It then sets the vector to its 


Listing 2 continued 


/* push ds */ 

_asm 

push 

ds 

/* Save DGROUP. 

*/ 

/* mov ds, cs:[0030] */ 

_asm 

mov 

es, reg.wES 

/* Restore original 

*/ 

/* This enables me to keep a permanent jump */ 

_asm 

mov 

ds, reg.wDS 

/* register set. 

*/ 

/* instruction to Hook21 at the start of the */ 

_asm 

mov 

di, reg.wDI 



/* ISR. Then to call the ISR, I replicate the */ 

_asm 

mov 

si, reg.wSI 



/* effect of executing the above 2 instructions */ 

_asm 

mov 

bx, reg.wBX 



/* and jump to the third instruction in the ISR. */ 

_asm 

mov 

dx, reg.wDX 



asm push es 

asm 

mov 

cx, reg.wCX 



asm mov es, wSel 

asm 

mov 

ax, reg.wAX 



asm mov ax, es:[0030h] 

_asm 

push 

reg.wFlagReg 



_asm mov wSelPriv, ax 

asm push 

cs 

/* Make it a far call 


asm pop es 

_asm 

call 

LCal1Isr 

/* Hack-o-rama. 


goto LSkipCalllsr; 

_asm 

mov 

reg.wES, es 

/* Save register set 

for 


_asm 

mov 

reg.wDS, ds 

/* for return to caller. 

LCal1Isr: 

_asm 

mov 

reg.wDI, di 



asm push ds 

_asm 

mov 

reg.wSI, si 



asm mov ds, wSelPriv 

_asm 

mov 

reg.wBX, bx 



asm jmp DWORD PTR lpfn 

_asm 

mov 

reg.wDX, dx 



/* We have now transferred control to the ISR */ 

_asm 

mov 

reg.wCX, cx 



/* which will iret, so control is never returned */ 

_asm 

mov 

reg.wAX, ax 



/* here. */ 

_asm 

pushf 





_asm 

pop 

reg.wFlagReg 



LSkipCalllsr: 

_asm 

pop 

ds 

/* Our DGROUP. */ 




$3 


Dynamic Link Library 

'Adldl3V <fraf>k/cs toyx>ur U/Wowsprogram/' 

- more then 300 functions - 

- Wireframe, Flat, Gouraud and Phong Shading - 

- unlimited number of Displays (windows) - 
- unlimited number of Viewports per Display - 

- contents of Display or Viewport can be saved as bitmap file - 

- unlimited number of colored Point, Direction and Spot lamps ■ 

- Clipping Planes, parallel and perspective projection - 

- renders fully cooperative / preemptive / in the background - 

- renders in any window or creates own windows - 
- Animation and Double Buffering - 

- Hierarchical Object Oriented data storage - 

- 350 page manual - 

Ve#efof> sophisticated3Dgraphics applications/' 

3D RenderLib for Windows 
JA $298.00 

(no runtime royalties) 

3rd Floor Graphics Software 
P.O.Box 4105, 9701 EC Groningen, The Netherlands 
fax: (+31) 50 184190 


if (!(reg.wFlagReg & 0x0001)) /* Successful? */ 
switch (wFunction) 

{ 

default: 

break; 


case Ox3cOO: 
case Ox3dOO: 
case 0x5a00: 
case 0x5b00: 


/* Create. */ 

/* Open. */ 

/* Create temporary. */ 
/* Create new. */ 


NotifyOpen(MAKELP(reg.wDS, reg.wDX), 
reg.wAX); 
break; 

case Ox3eOO: /* Close. */ 

NotifyClose(reg.wBX); 
break; 

case 0x4500: /* Duplicate. */ 

NotifyDuplicate(reg.wBX, reg.wAX); 
break; 

case 0x4600: /* Force. */ 

NotifyDuplicate(reg.wBX, reg.wCX); 
break; 

case 0x6c00: /* Extended open/create. */ 

NotifyOpen(MAKELP(reg.wDS, reg.wSI), 
reg.wAX); 
break; 


void 

Notify0pen(LPSTR IpszFile, int wHandle) 

^*****************************************************j 

/* — Add the file to the list and notify the client */ 
/* the list has changed. */ 

/*****************************************************/ 

{ 


□ Request 209 on Reader Service Card □ 


Page 60 — Windows/DOS Developer's Journal 


October 1993 























intercept routine using INT 0x21, function 0x25. UEP() 
removes the intercept by restoring the original ISR. I used im- 
plib to generate a .lib file for notify.dll, and linked it into 
filelist.exe, so that Windows would implicitly load 
notify.dll when it started up filelist.exe. 

After putting all the pieces in place, I fired up Windows. 
Everything seemed to be working okay. I could see a couple 
of files opened on behalf of Program Manager, but when I 


Listing 2 continued 


long iofi; 

OFI huge * gpofi; 

WORD pdb = PdbGetCur(); 

if (cofi == cofiUsed) 

return; /* Out of space. */ 

/* Check for duplicates. */ 

for (iofi = 0, gpofi = gprgofi; iofi < cofiUsed; 
iofi += (gpofi++)->pdb != 0) 
if (gpofi->pdb »■ pdb && 
gpofi->wHandle == wHandle) 
return; /* Duplicate. */ 

/* Find a free slot in the list. */ 
for (iofi « 0, gpofi = gprgofi; iofi < cofi; 
gpofi++, iofi++) 

if (gpofi->pdb == 0) 

( 

/* Add info to list. */ 
gpofi->wHandle = wHandle; 

CopyLpsz(gpofi->szPath, 1pszFi1e); 

gpofi->pdb = pdb; 

cofiUsed++; 

NotifyO; /* Inform client. */ 
break; 

I 

) 

WORD 

PdbGetCur(void) 

/* -- Return the current PDB. */ 

^★*★*★*****★★*★****★★★***★**★★*★★★**★*★******★*★*★★★**i 

WORD pdb; 

_asm mov ax, 5100h 

_asm int 21h 

_asm mov pdb, bx; 

GetCurrentTask(); 
return pdb; 

I 

void 

Notify(void) 

j *★★★★★★*★★★★★**★★★**★**★**★*'* ★★**★★******★★*★★**★****i 

/* -- Post notification that file list has changed. */ 

j *********************★**★**★*★*★★***★********* *******J 

I 

if (IsWindow(hwndNotify)) 

{ 

if (IfNotified) 

I 

fNotified = TRUE; 

PostMessage(hwndNotify, WM_USER, 0, 0); 

I 

} 

else 

hwndNotify * NULL; 

I 
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Listing 2 continued 


void 

CopyLpsz(LPSTR IpszDest, LPSTR IpszSrc) 

I * ************ ****************************************j 

/* -- Our own version of IstrcpyO, since it needs */ 

/* to be called at interrupt time. */ 

^*****************************************************/ 
< 

while ((*lpszDest++ * *lpszSrc++) != 0) 

} 

void 

NotifyClose(int wHandle) 

j***************************************************** J 

/* -- Remove the file from the list and notify the */ 

/* client the list has changed. */ 

j*****************************************************j 
{ 

OFI far * lpofi; 

/* See if the file is on the list. */ 
if ((lpofi * LpofiFind(wHandle)) 1= NULL) 

( 

/* Remove from list. */ 
lpofi->pdb * 0; 
cofiUsed—; 

NotifyO; /* Inform client. */ 

) 

} 

OFI far * 

LpofiFind(int wHandle) 


exited filelist.exe and did anything else in Windows, it 
promptly crashed, spewing large amounts of output to my 
debug terminal. It turns out the problem is with the INT 0x21 
set vector service (I found this out after tediously disassem¬ 
bling the INT 0x21, function 0x25 service code). 

As I said earlier, Windows installs its own protected-mode 
ISR for both file I/O and the get and set vector functions that 
notify.dll uses to intercept file opens and closes. The 
protected-mode ISR performs a sanity check before actually 
carrying out the request. The check ensures that a private flag 
must be set before it will let you change the INT 0x21 ISR. 
(Actually, the protected-mode version of this service changes 
the IDT. The flag is at offset 0x034C in a private KERNEL data 
segment in the debug version or 0x032C in the retail version.) 
Terminating filelist.exe caused Windows to unload 
notify.dll, after first calling its WEP() (the DLL termination 
routine) function. NEP()' s call to set the ISR back to the 
original KERNEL ISR was failing this test. As a result, the first 
INT 0x21 made after notify.dll had been unloaded was 
trying to jump to code in notify.dll that was no longer in 
memory. Kaboom. Why did the set vector service work in 
LibMain() but not in the WEP()1 Or, equivalently, what was 
the purpose of this mysterious flag in KERNEL that had the 
power to disallow attempts to change the INT 0x21 ISR? 

Why Set Vector Fails 

It’s at times like this that I feel eternal gratitude to Intel for 
introducing the debug registers in the 80386. Both WDEB386 
and Soft-ICE/W use them to implement hardware watchpoints. 
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You specify the address and the type of access (read, write, or 
execute), and when it happens, the CPU transfers control to 
the debugger. Unlike the software watchpoints implemented 
by some debuggers, hardware watchpoints do not incur a 
severe performance hit. The WDEB386 command is “br”; Soft- 
1CE/W uses "bpm". So, I set a watchpoint on the mysterious 
flag in KERNEL to see who was clearing it. It was happening 
shortly after LibMain() returned, inside the call to InitTask() 
during filelist.exe's startup. InitTask() is a special Win¬ 
dows function that an application must call immediately at 
startup. Your compiler's runtime library handles this for you, 
so you normally don't have to know anything about Init- 
Task(). 

It turns out that InitTaskf) executes some special code 
for the first task that Windows executes. This special code, 
among other things, clears the mysterious flag in KERNEL. The 
intent is clear. By the time the very first Windows task 
reaches UinMainQ, Windows does not want INT 0x21 to 
change. The loophole Microsoft missed was an implicitly 
loaded DLL issuing an INT 0x21, function 0x25 from its Lib- 
Main(), since that particular piece of code is executed before 
InitTask() clears the flag. That meant it was sheer luck that 
the first call to change the INT 0x21 ISR worked. If 1 had tried 


to do all the work from a task, and not use a DLL, every 
attempt to set the INT 0x21 ISR would have failed. 

So, back to the drawing board. As a quick hack, I reset the 
private KERNEL flag in the WEP() before restoring the original 
ISR (the private KERNEL data segment is embedded in various 
KERNEL code segments at various offsets-, this particular code 
segment kept it at offset 0x0030). This actually seemed to 
work. I could exit filelist.exe and the system continued to 
function. Just to make sure everything was indeed working, I 
wrote a tiny program that opened a file, put up a message 
box, closed the file, and exited. I wanted to see the file in the 
list while the message box was up. Well, the file didn’t show 
upl 

I should have known better, since there is an API function 
called D0S3Cal l () that, according to the SDK docs, “runs 
somewhat faster than the equivalent MS-DOS Interrupt 21h 
function running in Windows.” Why raise an INT 0x21 when 
DOS3Cal l () can provide the same functionality, only faster? In 
fact, I discovered that API functions such as _lopen() and 
_lcreat() don’t even use D0S3Call(), they just call the ad¬ 
dress of the INT 0x21 ISR directly. No wonder Windows is 
preventing an attempt to change the INT 0x21 ISR! The flag 
at offset 0x034C (or 0x32C) is an attempt to ensure Windows’ 



j*****************************************************J 


I*****************************************************/ 


/* -- Find the file handle for the current task. */ 
/* -- Return NULL if not found. */ 

j***************************************************** I 
( 

long iofi; 

OFI huge * gpofi; 

WORD pdb = PdbGetCur(); 

for (iofi = 0, gpofi * gprgofi; iofi < cofiUsed; 
iofi += (gpofi++)->pdb != 0) 
if (gpofi->pdb == pdb && 
gpofi->wHandle == wHandle) 
return gpofi; 

return NULL; 

} 

void 

NotifyDuplicate(int wHandleOrig, int wHandleNew) 

j*****************************************************j 

/* — Add the duplicate handle to the list. */ 

I **************** ***************************** ********J 
{ 

OFI far * lpofi; 

/* See if the file is on the list. */ 
if ((lpofi = Lpofi Find (wHandleOrig)) != NULL) 

NotifyOpen(1pofi->szPath, wHandleNew); 

} 

void WINAPI _export 

SetPostWnd(HWND hwnd) 

I *****************************************************j 

/* -- Set the window to receive notifications. */ 

j*****************************************************j 
{ 

hwndNotify = hwnd; 

i 

BOOL WINAPI _export 

FNext0fi(0FI far * lpofi, long far * lpiofi) 


/* -- Client service. */ 
/* -- Return the next file in the list to the */ 
/* client. */ 
/* -- Call with *1 pi ofi set to -1 to begin */ 
/* enumeration. */ 
/* -- Updates lpiofi to next entry each call, */ 
/* returns FALSE once all entries have been */ 


/* enumerated (in which case *1pofi is invalid). */ 

f*****************************************************j 
( 

if (fNotified) 

{ 

fNotified * FALSE; /* Ok to notify again. */ 

/* Grow list? */ 

if (cofi - cofiUsed < cofiLow) 

{ 

OFI huge * gprgofiNew; 

if ((gprgofiNew = GlobalReAllocPtr(gprgofi, 
(cofi + dcofi) * sizeof(OFI), 

GMEMJHARE | GMEM_M0VEABLE | 
GMEM_ZER0INIT)) != NULL) 

{ 

gprgofi - gprgofiNew; 
cofi += dcofi; 

1 

1 

1 

/* Is the list empty? *1 
if (cofiUsed — 0) 
return FALSE; 

/* Find the next file. */ 
for (++*lpiofi; ‘lpiofi < cofi; ++*1 pi of i) 
if (gprgofi[‘lpiofi].pdb !* 0) 

( 

‘lpofi = gprgofi[‘lpiofi]; 
return TRUE; 

1 

return FALSE; 

1 

/* End of File */ 
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Table 1 Table of file open/close functions 

Function 

Purpose 

Input Parameters 

OutputParameters 

0x3c 

Create file 

DS:DX far pointer to file name 

CX file attributes 

AX file handle 

0x3d 

Open file 

DS:DX far pointer to file name 

AL open mode 

AX file handle 

0x3e 

Close file 

BX file handle 

None 

0x45 

Duplicate file 

BX existing file handle 

AX new file handle 

0X46 

Force duplicate 

BX exisiting file handle 

CX required new handle 

None 

0x5a 

Create temp, file 

DS:DX far pointer to path name 

CX file attributes 

AX file handle 

0x5 b 

Create new file 

DS:DX far pointer to file name 

CX file attributes 

AX file handle 

0x6c 

Extended open 

DS:SI far pointer to file name 

BX open mode 

CX file attributes 

DX action code 

AX file handle 

Note: For each of the listed functions the carry flag is set upon return to indicate an error, or clear if the function was 
successful. If the carry flag is set, the value returned in AX is an error code. 
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Listing 3 filelist.c - Source for program to display open files 

^**************************************ilr************** ^ 

LRESULT CALLBACK export 

/* filelist.c */ 

LwWndProc(HWND hwnd, UINT wm, WPARAM wParam, 

/* — Program tracks open files per task. */ 

LPARAM IParam) 

/* -- Called before progman so it can track */ 

j★***★*★*★*★★★★★**★*★★**★*★★*★★**★★★★+*★★★★★*★★★★★★★*★j 

/* progman's files as well. */ 

/* -- Main window procedure. */ 

/* — To build: */ 

j sir**************************************************** j 

/* cc -DSTRICT filelist.c toolhelp.lib notify.lib */ 

i 


switch (wm) 

#include <windows.h> 

{ 

default: 

linclude <windowsx.h> 

break; 

#include <toolhelp.h> 


linclude "notify.h“ 

case WM CREATE: 

Idefine cidList 1 /* Listbox control id. */ 

if (CreateWindow(”ListBox“, NULL, 

WS CHILD | WS VSCROLL | WS VISIBLE, 0, 0, 0, 

char szClass[] » "FileList"; /* Class name. */ 

0, hwnd, (HMENU)cidList, 

GetWindowInstance(hwnd), NULL) == NULL) 

char szShell[] * "Progman"; 

return -1; 

/* Internal prototypes. */ 

FillList(hwnd); 
break; 

void GetSzPdb(PSTR, WORD); 


void Fill List(HWND); 

case WM SIZE: 

/* Exported prototypes. */ 

SetWindowPos(GetDlgItem(hwnd, cidList), NULL, 

0, 0, LOWORD(lParam), HIWORD(lParam), 

LRESULT CALLBACK export 

SWP NOMOVE | SWP NOACTIVATE | SWP NOZORDER); 

LwWndProc(HWND, UINT, WPARAM, LPARAM); 

break; 

int PASCAL 

case WM DESTROY: 

WinMain(HINSTANCE hins, HINSTANCE hinsPrev, LPSTR lpsz. 

PostQuitMessage(O); 

int wShow) 

break; 



/* -- Entry point. */ 

case WM USER: 

y*****************************************************^ 

( 

Fill List(hwnd) ; 

break; 

HWND hwnd; 

) 

MSG msg; 


if (hinsPrev == NULL) 

/ 

return DefWindowProc(hwnd, wm, wParam, IParam); 

) 

\ 

WNDCLASS wcs; 

void 

wcs.style = CS HREDRAW | CS VREDRAW; 

Fill List(HWND hwnd) 

j*****************************************************J 

wcs.lpfnWndProc = LwWndProc; 

/* -- (Re)Fill the file list with entries. */ 

wcs.cbClsExtra = 0; 

/*****************************************************^ 

{ 

wcs.cbWndExtra = 0; 

wcs.hlnstance = hins; 

long iofi = -1; 

wcs.hIcon = LoadIcon(NULL, IDI APPLICATION); 

OFI ofi; 

wcs.hCursor s LoadCursor(NULL, IDC ARROW); 


wcs.hbrBackground = (HBRUSH)(COLOR WINDOW + 1); 

hwnd = GetDlgltem(hwnd, cidList); 

wcs.1pszMenuName = NULL; 

SendMessage(hwnd, WM SETREDRAW, FALSE, 0); 

wcs.1pszClassName = szClass; 

SendMessage(hwnd, LB RESETCONTENT, 0, 0); 

if (!RegisterClass(&wcs)) 

while (FNextOfi(&ofi, &iofi)) 

{ 

return FALSE; 

char szBuf[256]; 

) 

char szName[MAX_MODULE_NAME + 1]; 

msg.wParam * 0; 

GetSzPdb(szName, ofi.pdb); 

if ((hwnd » CreateWindow(szClass, szClass, 

wsprintf(szBuf, “%x(%s): %d %s". 

WS OVERLAPPEDWINDOW, CW USEDEFAULT, 

ofi.pdb, (LPSTR)szName, ofi.wHandle, 

CW USEDEFAULT, CW USEDEFAULT, CW USEDEFAULT, 

(LPSTR)ofi.szPath); 

NULL, NULL, hins, NULL)) != NULL) 

SendMessage(hwnd, LB ADDSTRING, 0, 

{ 

(LPARAM)(LPSTR)szBuf); 

SetPostWnd(hwnd); 

) 

if (GetModuleHandle(szShell) ■» NULL) 

SendMessage(hwnd, WM SETREDRAW, TRUE, 0); 

WinExec(szShell, SW SHOWNORMAL); 

InvalidateRect(hwnd, NULL, TRUE); 

ShowWindow(hwnd, wShow); 

( 

while (GetMessage(&msg, NULL, 0, 0)) 


{ 

void 

TranslateMessage(&msg); 

GetSzPdb(PSTR pszName, WORD pdb) 

DispatchMessage(&msg); 

^★★★★*************************************************y 

) 

/* -- Attempt to find the module name for the given */ 

1 

/* PDB. */ 

return msg.wParam; 

/* -- Returns the string "system" if not found. */ 

) 

y*****************************************************y 

{ 


Page 66 — Windows/DOS Developer’s Journal 


October 1993 






integrity. When i finally understood its intent, it was like 
seeing a shrunken head dangling from a piece of bamboo 
deep inside a tropical rain forest. 

Patch-Based INT 0x21 Interception 

Time for another attempt. Windows obviously does not 
want the INT 0x21 ISR changed, but it is possible to use a 
technique I have used a couple of times in the past to replace 
the code at the entry to the ISR with a jump to a hook func¬ 
tion (see the May and August Q6cA columns). One problem 
with that technique is that the INT 0x21 ISR can be called in 
the middle of servicing a previous INT 0x21 request. An ex¬ 
ample is function 0x4C, “terminate application,” which is also 
used to terminate a Windows application. This service issues 
INT 0x21, function 0x3E to close each file left open by the 
application. 

The technique I used in previous columns depends on 
patching the target function so that it jumps to my intercept 
function, and then immediately unpatching the target function 
so that I can call it directly after spying on the input argu¬ 
ments or whatever. After calling the unpatched target func¬ 
tion, I then patch it again so that any future calls jump to my 
intercept function again. That won't work correctly with INT 
0x21, since after unpatching it and then calling it to get the 
work done, it could call itself before returning and my inter¬ 
cept function would not get control during the re-entrant call. 

I can think of two ways around this, but both of them 
have problems. The first is to use the 80386 debug registers. 
Your code can set an address and access type to break on, 
just like a debugger, and you could use this feature to trap 
calls to the ISR routine in KERNEL. The problem is that access 
to the debug registers is restricted to privilege ring 0, which 
means either writing a VxD or using a call gate trick like the 
one Matt Pietrek presented in his article, "Run Privileged Code 
from Your Windows-based Program Using Call Gates,” in the 
May 1993 Microsoft Systems Journal. Further, both of those 
techniques depend on running Windows in enhanced mode. 

The other solution is a modification of my original function¬ 
patching technique. The problem with the original technique is 
that I have to unpatch the target function long enough to call 
it myself. What I really need is two versions of the target 
function: one copy that stays patched with a jump to my in¬ 
tercept routine and an unpatched private copy that I can call 
myself from the intercept routine. If you think about it, the 
unpatched private copy would be exactly the same as the 
patched version, except for the very beginning, where I install 
a far jump instruction. 

My solution, then, is to create a small function that con¬ 
tains the same initial instructions as the unpatched version of 
the ISR in KERNEL. It only has to contain the initial instructions 
that get clobbered by the patched-in jump instruction, and 
then it can just jump directly to the body of the original ISR 
code, safely bypassing the modified instructions in the original 
function. This lets me leave the far jump in place permanent¬ 
ly and redirect every call to the ISR to the intercept function 
(since the ISR resides in a fixed code segment, you don’t have 
to worry about it being discarded and having to replace the 
jump). Figure 1 shows the basic technique for patching a 


Listing 3 continued 


TASKENTRY tke; 

tke.dwSize = sizeof tke; 
if (TaskFirst(&tke)) 
do 

if (tke.wPSPOffset == pdb) 

{ 

lstrcpy(pszName, tke.szModule); 
return; 

} 

while (TaskNext(&tke)); 

lstrcpy(pszName, "system"); 

) 

/* End of File */ 


reentrant function. The specific code I will use is a little dif¬ 
ferent, but the figure demonstrates the general concept. 

The downside of this technique is that it depends com¬ 
pletely on duplicating the specific instructions in the target 
function that get replaced by the far jump. If a future version 
of Windows has different code at the start of the ISR, this 
technique will fail. The choice, as I see it, is between an en- 
hanced-mode-only solution with some extra ring 0 code that 
may not work with a future version of Windows and a truly 
version-dependent solution that does not require ring 0 
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FileList 


b7[system): 16 C:\WIN3.1\SYSTEM\TIMER.DRV 

b7(system): 8 C:\WIN3.1\SYSTEM\SBPSND.DRV 
b7(system): 17 C:\WIN3.1\SYSTEM\MIDIMAP.DRV 
b7(system): 14 C:\WIN3.1\SYSTEM\MMSYSTEM.DLL 
b7(system): 15 C:\WIN3.1\SYSTEM\DRIVERS.CPL 
b/(system): 18 C:\WI N3.1\SYSTEM\CPWIN 386.C PL 
..:. 


6 C:\WIN3.1\GL0SSARY.HLP 



: 


Figure 2 filelist.exe in action 


coding. Neither choice is particularly appealing, but I chose the 
latter since it was the easier of the two evils to implement. 


function at the start of the current ISR. LibMain() uses the 
GMEM_SHARE flag when it allocates global memory so that the 
memory is owned by the DLL, not the task that invoked it (in 
case some other task wants to make use of the notify.dll). 
The UEP() unpatches the ISR by restoring the code that was 
clobbered by the patched-in far jump. 

Hook21 () is the hook (or intercept) function and contains 
the version-dependent code. I wanted to use a C function to 
hook the ISR, which meant preserving registers on entry. The 
routine also needs to be exported to gain access to the DLL’s 
DGROUP. The prologue for an exported function will destroy AX, 
but fortunately Microsoft C supports a language extension, 
_interrupt. When this keyword is used in a function decla¬ 
ration, the compiler saves most of the registers on entry by 
emitting: 


The Implementation 

notify, h (Listing 1) contains the interface that the client 
application uses to access notify.dll. It defines a list entry 
structure and exports two functions to the client. The client 
calls SetPostWnd() to register a window handle to which the 
DLL will post notifications. The client calls FNextOfi() to 
iterate through the list of open files. 

notify.c (Listing 2) contains the source code for the DLL 
Due to incompatibilities in inline assemblers, the code unfor¬ 
tunately only works with Microsoft C/C-++ compilers. In Lib- 
Main (), notify, c preallocates some space for the list of open 
files, initializes some global variables, stores the address of the 
current INT 0x21 ISR, and installs a far jump to the intercept 
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pusha 
push ds 
push es 

Since these are on the stack, they can be accessed as if they 
were parameters, so I defined a structure, REG, that lists its 
members in the inverse order that they were pushed on the 
stack (since the stack grows down). Hook21 () is declared using 
a REG parameter which allows access to the saved registers. I 
also tacked the return address and flags to the end of the 
structure, since these are the first things to be pushed when 
calling an ISR. 

The far jump instruction is five bytes long and destroys 
the first two instructions of the INT 0x21 ISR, which the 
debugger reveals to be: 

push ds 

mov ds, word ptr cs:[0030] 

The next instruction in the ISR begins six bytes from the start. 
In order to duplicate the effects of the first two instructions, l 
obtain the private KERNEL selector stored at offset 0x0030 in 
the code segment containing the ISR, so I can load it into DS 
just before the small helper function jumps to the instruction 
starting six bytes from the beginning of the ISR. I chose to 
embed the small helper function inline with Hook21 () so that 
it would have access to Hook21 ()'s local variables. After stor¬ 
ing the private KERNEL selector in the variable wSelPriv, the 
code jumps around the inline helper function to code that 
restores the registers (copies them from the REG parameter), 
and calls the helper function. 

Just before calling the helper function, I push the flags 
register and the CS register onto the stack. The flags are ob¬ 
tained from the REG structure, and are required since the ISR 
returns with an IRET. I couldn’t figure out how to get the 
compiler to generate a far call to a label, so I simply pushed 
CS before calling to the address specified by the label LCall- 
Isr. A far call is necessary so that the stack resembles what 
it looked like when the ISR's entry point was called. The hel¬ 
per function jumps to the instruction at offset six from the 
start of the ISR. When the ISR returns (by executing an IRET 
instruction), control returns to the instruction following the call 
to the helper function. 
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Since Hook21() is declared with the_ interrupt keyword, 

the compiler generates exit code that pops the saved 
registers, the return address, and the flags register. Since I 
want to return the registers set by the 1SR, I store them back 
into the REG parameter after the ISR returns. The REG 
parameter is akin to the Client structure in a VxD - it is an 
image of the registers that are obtained from, and will be 
returned to, the client. The flags register of the REG structure 
maps to the location of the flags register image that was 
pushed when the original ISR was called. The flags register 
returned from the. actual ISR call is stored back into the 
reg.wFlags field, so that when Hook21() returns with an 
I RET, the flags returned from the actual ISR are returned to 
the caller. 

After the ISR returns, Hook21 () has to determine if a file 
was opened or closed and modify the file list appropriately. 
The ISR must be called first, both because the call could fail 
(carry flag is set), and because, in the case of a call to open or 
create a file, the routine must obtain the file handle to be 
associated with the file name in the list. The switch state¬ 
ment in Hook21 () calls the appropriate routine for each ser¬ 
vice that can change the file list. Table 1 lists the INT 0x21 
functions that manipulate file handles and their parameters. 
You will notice that function 0x4C, “end program," has been 
omitted. This function, which closes all open files, doesn't have 
to be trapped because it generates a separate INT 0x21, 
function 0x3E to close each open file. 

The routines NotifyClose(), NotifyDuplicatef), and 
NotifyOpen() maintain a list of type OFI (Open File Info, 
defined in notify.h). In addition to a file handle and path 
string, OFI has an entry for the task's PDB, which must be 
used instead of the task handle to identify the owner of an 
open file. The .exe file is closed during task termination, but 
calling GetCurrentTaskf) returns the handle of the terminat¬ 
ing TDB rather than the parent task that opened the . exe file. 
The problem arises because GetCurrentTask() returns the 
value stored in a global variable that has not been updated 
yet. Similarly, GetCurrentPDB() returns a value that is stale at 
task termination time. The solution is to issue an INT 0x21, 
function 0x51, “get PSP address.” The INT 0x21 ISR returns the 
protected-mode version of this function, a selector to the PDB 
that really owns the file handle being manipulated. 

The list is implemented as a huge array to accommodate 
more than 512 open files. In addition to maintaining the size 
of the array ( cofi ), the code keeps a count of the number of 
used slots in the array (cofiUsed). Notify0pen()'s first task is 
to test that these numbers are not the same, since that 
would mean the array is full. To be robust, NotifyOpen() then 
checks that the current file handle and PDB pair are not al¬ 
ready in the array. It then calls the helper function PdbGet- 
Cur(), which uses INT 0x21, function 0x51 t 
o get the current PDB. The loop to check for duplicates counts 
the used entries and stops when cofiUsed of them have 
been encountered. This small optimization may allow the loop 
to terminate before searching the entire list. 

If no duplicate is found, NotifyOpen() then searches for 
the first unused entry, which will have a NULL value for the 
PDB structure member. On finding a free entry, NotifyOpen() 
stores the path name, PDB, and file handle in the entry, in¬ 


creases the usage count, and notifies the client that the list 
has changed by calling the helper routine Notify(). In place 
of _lstrcpy(), I use a private string copy function, Copy- 
Lpsz(), to copy strings, since the routine needs to run at in¬ 
terrupt time. 

Notify() checks that the client window handle is valid 
and clears the handle if it is not, in case the client window 
has been destroyed for some reason. The various “Is” func¬ 
tions (such as IsWindow()) don’t work here, since handles can 
be reused. In fact, it is all too easy to destroy a window and 
create a new one that reuses the old handle: this is a con¬ 
stant source of bugs in poorly designed application code. By 
zeroing the window handle NotifyO provides some security, 
but this is still not bulletproof. To be truly robust, any DLL that 
keeps window handles should install a toolhelp Notify- 
Register() routine that can track task termination even 
when a task UAE’s. 

After validating the window handle, NotifyO checks a flag 
to see whether the client has already been notified before 
posting it a UM_USER message. The flag is cleared when the 
application calls back to the notify.dll to receive the list. 
This helps prevent overflowing the client's message queue 
(the default size is only eight messages), since, potentially, 
many file operations can occur before a task yields. 

NotifyClose() calls the helper function LpofiFind() to 
see if the given file handle and current PDB are on the list. If 
they are, LpofiFind() returns a far pointer to the open file 
information entry (the pointer does not need to be huge if it 
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is not to be manipulated); if not, it returns NULL. For each 
entry it finds on the list, NotifyClose first marks the entry as 
free by setting the PDB member to NULL, then decrements the 
usage count. 

NotifyDuplicatef) calls LpofiFind() to see if the handle 
being duplicated is on the list. If so, it uses NotifyOpen() to 
add the old file name with the new handle. 

SetPostWnd() is exported to the client. It is the mechanism 
the client uses to register a window to receive notifications. 
The only task here is to remember the window handle (in the 
global variable hwndNotify). 

The last routine in the DLL is FNextOfi(). It too is an ex¬ 
ported service; the client application uses this routine to 
iterate over all the used entries in the list. It accepts a pointer 
to the current entry index, as well as a pointer to an OFI to fill 
with the contents of the entry. To perform the iteration, the 
client sets the index to -1, then calls the function in a loop 
until it returns FALSE. As already mentioned, the code clears 
the notified flag if it was set (meaning the client is responding 
to a posted WM_USER message), and grows the array if it has 
come within a threshold of being full (I am using an increment 
size of 100 entries with a threshold of 50). The routine then 
falls into a loop that scans for the next used entry. 

filelist.c (Listing 3) contains the source code for the 
client application (see Figure 2) that maintains the window of 
open files. UinMainf) registers a class and creates the main 
window and then registers the window handle with 
notlfy.dll. NinMainf) then invokes Program Manager if it is 


The help authoring solution for Windows 


WYSI-Help 



Our WYSIWYG editor shows you what the final help will look like as you are creating it. To link your help topics to a context you just click 
with the mouse on the button, menu, or listbox you wish to explain WYSI-Help is compatible with any programming language as well as none 
at all. So you can put help on any application without touching the programming sources. 


This product is now available through I BM's recently announced TRY & BUY technology. 

This means you can download it this very minute from CompuServe® at no additional charges. You pay only your regular 
CompuServe® charges Then you can try WYSI-Help for 30 days and later decide to buy it. 

_ DDTEC 1-800-289-1948 _ 

□ Request 216 on Reader Service Card □ 


not already running. The main window procedure creates a 
child listbox control and ensures that it fills the client area by 
resizing the listbox whenever a UM_SIZE arrives for the main 
window. When a UM_USER message is received (indicating that 
notify.dll has made a change in its list), the helper routine 
Fill List () displays the contents of the file list in the listbox. 

Fill List () first empties the listbox, then tells it not to 
display updates (via the UM_SETREDRAU message). After the list 
has been filled, another UM_SETREDRAW turns updates back on 
and the client area of the list box is invalidated so that it will 
display its new contents. FNextOfi () is called in a loop to 
retrieve the OFI for each open file. 

The helper routine GetSzPdb() converts the PDB field of 
the OFI into a task name; wsprintfO formats the OFI and 
the task name into an ASCII string, and the string is added to 
the list box. GetSzPdb() uses the TOOLHELP routines Task- 
First() and TaskNext() to walk the task list. If the value 
returned in the TASKENTRY structure's member wPSPOffset 
matches the PDB selector passed in, the module string is 
returned (via the pszName parameter). Don't be put off by the 
SDK’s description of the wPSPOffset field as specifying “the 
offset from the program segment prefix (PSP) to the beginning 
of the executable code segment”: I don’t know where this 
description came from, but it is nonsense. In reality, the field 
contains a selector that references the start of the PDB inside 
a task’s TDB. If no task can be found with the given PDB, the 
name returned is "system” (it sounded better than saying “un¬ 
known"). 

After building notify.dll and filelist.exe, placing them 
both in the system subdirectory (this is simply my preference, 
they can go anywhere on your path), and changing the “shell" 
line in system.ini to read “shell=filelist.exe", the program is 
ready to roll. When I ran it (by invoking Windows), I noticed 
that a lot of files owned by “system" were showing up. These 
were the files being held open by KERNEL. It turns out that 
KERNEL implements a file handle cache. When a new file has 
to be opened and the cache is full, an older one is first closed 
to free a file handle. 

It’s interesting that the file handle table in the PDB 
reported by filelist.exe (obtained from the INT 0x21, func¬ 
tion 0x51) does not correspond to the file handles held by 
KERNEL. I don’t know what magic is taking place to remap 
KERNEL'S PDB handle table, or even who the owning program 
is, for that matter, so if you uncover this stuff, please let me 
know what you find. 

The astute reader may have noticed that even though the 
code does not call a Windows function at interrupt time, it 
does make use of INT 0x21, function 0x51 to obtain the cur¬ 
rent PSP. As far as I have been able to ascertain, Microsoft has 
not taken a stance on the availability of DOS interrupt services 
at interrupt time. Certainly DOS itself makes use of them. This 
is another reason why I consider this code useful for a debug¬ 
ging aid but not for commercial software. It appears to run 
well enough, but that of course is no guarantee that it will 
run safely on your system under all circumstances. □ 
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tricks and hacks —those 
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make things work the 
way they should! You’ll 
receive at least $50 for 
each tip that we print. 
Send your submissions to.- 
Tech Tips 
Leor Zolman 
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An Owl Class for Status 
Lines, and Persistent 
DOS Directories 


Restoring Current Drive/Directory Associations 


Scott A. Mintz 
Reliance Electric 
24800 Tungsten Road 
Euclid, OH 44117 
71461,632 

sam@rrc.mhs.compuserve.com 

One really nice feature of BRIEF and CodeWright is the ability to reload all the files 
that were worked on last. This feature recreates the open windows, reloads the 
buffers, and positions you on the character where you left off. 1 thought it would be 
a good idea to extend this metaphor to the DOS environment as well. I work on a 
network with a relatively large number of drive mappings. I have come up with a 
very simple batch file that restores the current working directory (CWD) on all my 
network and local drives and makes the last drive I was in current. 

I created a batch file named logo.bat (Listing 1) that I use when logging off our 
network, logo.bat first calls savepath.bat (Listing 2), and then calls logout. 

When I log in, the last thing my login script does is execute restpath.bat. 



Leor Zolman wrote BDS Q the first C compiler targeted exclusively for personal computers. 
Leor is currently an instructor on UNIX topics for Boston University's Corporate Education 
Center, a regular contributor to Sys Admin magazine and “Tech Tips" editor for Win- 
dows/DOS Developer’s Journal. His first book, Illustrated C, was published by R&D Publica¬ 
tions, Inc in 1992. He may be contacted at 74 Marblehead St, North Reading, MA 01864, 
or on Usenet/Internet as.-1 eor@bdsoft. com. 
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savepath.bat creates restpath.bat 
(a sample restpath.bat is shown in 
Figure 1). The problem with creating 
restpath.bat is getting the “CDD " 
text and the current working directory 
on the same line in the batch file. The 
DOS echo command always appends a 
CR-LF to its text, so it cannot be used. 
The trick l employed was to create a 
text file with nothing but "CDD " in it 
(not even a trailing CR-LF). The follow¬ 
ing sequence of DOS commands creates 
such a file, named cdd.dat 

copy con CDD.DAT 
CDD *1 

Note the space after CDD but before the 
Control-Z. 

Then I type the file, redirecting the 
output to restpath.bat. This copies the 
text but does not insert a trailing CR-LF. 
Next I use the DOS cd command to 
return the CWD and append the output 
to restpath.bat. These two steps 
together appear as follows: 

type CDD.DAT > RESTPATH.BAT 
cd drive: » RESTPATH.BAT 

Since the cd command appends a CR- 
LF to its output, the result is a line with 
“CDD drive:\pathCR-LF” in it. 

The DOS cd command can restore all 
my working directories; but, it cannot 
restore the default drive. Since com¬ 
mand, corn's batch language provides'no 
means of even determining the default 
drive, I created a utility program named 
cdd.asm (Listing 3) which works like CD, 


Figure 1 Atypicalrestpath.bat 


Decho off 
COD C:\UTILS 
CDD F:\LOGIN 
CDD G:\C\BC\BIN 
CDD H:\CDD 

CDD I:\DPT\BUGFIX\INOUT 
CDD O:\AMXBASIC 
CDD L:\SAM\AMXBASIC 
CDD M:\S-ICE 
CDD H:\CDD 


Listing 1 logo.bat 


@echo off 
call savepath 
logout 


except that it selects the drive as well 
as the directory. If you are using 4D0S 
or NDOS, such a CDD command is al¬ 
ready built into your command proces¬ 
sor and you do not need my external 
version. 

cdd enables the default drive at the 
time of logout to be restored by virtue 
of its being the last driveApath written 
into restpath.bat. 



A Status Line Owl Class 


Jason M. Rinn 
3083C Whisper Lake Lane 
Winter Park, FL 32792 


Like most Windows programmers, I 
prefer to add nice finishing touches to 
my programs, especially visual ones. For 
a recent project, I decided that my pro¬ 
gram needed a status line. Most of the 
public domain solutions I've seen are 
for MDI applications, and while I could 
probably buy one of those predefined 
control class packages, I’m a hobbyist 
on a budget and I'd rather save for a 
better printer. Plus, I’d rather not have 
to stick with the dull static text control 
I prototyped with —it’s too bland. 

Listing 4 (status.cpp) and Listing 5 
(status.h) present my solution. It invol¬ 
ves deriving a class from the OWL class 
library in Turbo C++ for Windows or 
Borland C++. When you create your 
dialog box, place a static text control 
where you want the status line to ap¬ 
pear. Then, in the constructor for 
your dialog box object, create a new 
object of type TStatus, passing the 


Listing 2 savepath.bat 


@echo off 

echo @echo off > h:\restpath.bat 

type c:\utils\cdd.dat » h:\restpath.bat 

cd c:» h:\restpath.bat 

type c:\utils\cdd.dat » h:\restpath.bat 

cd f:» h:\restpath.bat 

type c:\utils\cdd.dat » h:\restpath.bat 

cd g:» h:\restpath.bat 

type c:\utils\cdd.dat » h:\restpath.bat 

cd h:» h:\restpath.bat 

type c:\utils\cdd.dat » h:\restpath.bat 

cd i:» h:\restpath.bat 

type c:\utils\cdd.dat » h:\restpath.bat 

cd j:» h:\restpath.bat 

type c:\utils\cdd.dat » h:\restpath.bat 

cd 1:» h:\restpath.bat 

type c:\utils\cdd.dat » h:\restpath.bat 

cd m:» h:\restpath.bat 

type c:\utils\cdd.dat » h:\restpath.bat 

cd » h:\restpath.bat 


Page 72 — Windows/DOS Developer’s Journal 


October 1993 



































Listing 3 cdd.asm 


************************************************************************** 


je 

ShowCwd 



* 




cmp 

al, 1 ' 

is it a space? 


* CDD.ASM 




je 

skip whitespace 

eat it if yes 


* 




cmp 

al,09h 

is it a tab char? 


* DESCRIPTION: 




je 

skip whitespace 

eat it if yes 


* This program performs the same function as MS-DOS' CD command, 






* however it changes the drive as well as the directory. 

store path 

label 

near 



* 




stosb 


save a char in my buffer 


* usage: CDD [Drive:][Directory] 



cmp 

al, ' 1 

is it a space 


* 




jle 

done 

or control char? 


* If neither Drive 

nor Directory are specified then CDD displays the 


cmp 

al, ’7' 

asking for help? 


* current working directory. 



jne 

@1 



* 




jmp 

Showllsage 



* REVISION HISTORY: 



01: 

lodsb 


get a char 


* 




jmp 

store path 

do some more 


* 18-Jun-1993 Scott 

A.Mintz 







* Original 


done 

1 abel 

near 



* 




dec 

di 



* Assembly/Linking instructions (Turbo Assembler): 


sub 

al ,al 

null terminate the string 


* tasm /q /m2 cdd 




stosb 




* tlink /t cdd 




mov 

al, '$' 

DOS Printstring terminator 


* (Generates CDD.COM) 




stosb 




* 




mov 

si.offset sPath 

point to copied path 


************************************************************************** 









mov 

ah,19h 

DOS GetDrive Command 

•MODEL 

tiny 



int 

21 h 

save it just in case 





mov 

bl ,al 

we need to restore it 

• CODE 







org 

lOOh 



cmp 

byte ptr [si+1], ' : 1 

was a drive specified? 





jne 

nodrive 


main label 

near 






mov 

di.offset sPath 

point to my buffer 


mov 

dl,[si] 

get the drive letter 

mov 

si,80h 

point to the command line 


or 

dl,20h 

map to lower case 

lodsb 


get byte count 


sub 

dl,' a' 

A=0, B=l, etc. 

sub 

ah,ah 



mov 

ah,0eh 

DOS SetDrive Command 

or 

al.al 

is it empty 


int 

21h 


jnz 

skip whitespace 

z means 





jmp 

ShowCwd 

just show where we are 


; since 

SetDrive never fails the only way of 





; knowing if we have a valid drive is to get 

skip whitespace label 

near 



; the " 

new" drive and see if it 

s the one 

lodsb 


get a byte 


; we set. 


cmp 

al,0dh 

is it a CR? 
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Listing 3 continued 


mov 

ah,19h 


DOS GetDrive Ccminand 


int 

21h 




cmp 

al ,dl 


same drive? 


je 

chkpath 


yes setdrive worked 


add 

dl,'a' 


map drive letter to ASCII 


mov 

cDrive.dl 


update the error message 


mov 

dl.bl 


restore original drive 


mov 

ah,0eh 


DOS SetDrive Command 


int 

21h 


call DOS 


mov 

dx,offset sBadDrive 


show the error 


jmp 

DisplayMsg 



chkpath 

label 

near 




cmp 

byte ptr [si+2],0 


path spec'd? 


je 

exit 


no, just change drive 

nodrive 

label 

near 




mov 

dx,si 


point to the path 


mov 

ah,03bh 


DOS ChDir Command 


int 

2 lh 




jnc 

exit 




mov 

dl.bl 


restore original drive 


mov 

ah,0eh 


DOS SetDrive Command 


int 

21h 




mov 

dx,offset sBadDirl 


show the error 


mov 

ah,09h 


DOS Printstring Command 


int 

2 lh 




mov 

dx,si 


display the bad path 


mov 

ah,09h 


DOS Printstring Command 


int 

21h 




mov 

dx,offset sBadDir2 


finish up 


jmp 

DisplayMsg 



ShowCwd 

label 

near 




mov 

di,offset sPath 


point to my buffer 


mov 

ah,19h 


DOS GetDrive Command 


int 

21h 


A*0, B*l, etc. 


add 

al,' A * 


map to ASCII 


stosb 



store the drive 


mov 

al. 1 : 1 




"I can't imagine why anyone would program 
without it...not using SafeWin is like 
programming blindfolded." 


SafeWin 


• No reprogramming—just relink with SafeWin 

• Detects resource leaks (global handles, cursors, 
icons,...) 

• Detects bad handles, bad GDI objects, thousands 
of potential error conditions 

• Traps NFY and RIP errors 

• Displays complete symbolic stack for each error 

• Records and displays window messages by symbol 
and value 

• Interactively change error traps, view resource 
usage, view reported errors, and more... 

• Use with MoreHeap for Windows to detect memory 
leaks, buffer overwrites, and view heap dumps for 
malloc’ed allocations. 

• Redirect reports to message box, debug monitor, 
or file 
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money back guarantee. 
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MoreHeap (DOS, 
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Listing 3 continued 



stosb 


store the colon 


mov 

al.'V 



stosb 


store the root directory 


mov 

si ,di 

current location in buffer 


sub 

dl.dl 

default drive 


mov 

ah,47h 

DOS GetCWD Command 


int 

21h 



mov 

si ,di 

reset the buffer pointer 

find end 

label 

near 



lodsb 


get a char 


or 

al ,al 

end of buffer? 


jne 

find_end 



dec 

si 



mov 

ax,0a0dh 

CR-LF 


mov 

di ,si 

point to the end 


stosw 


store a CR-LF 


mov 

al, '$' 



stosb 


store end of string char 


mov 

dx,offset sPath 

point to string 


jmp 

DisplayMsg 



exit 

label 

near 



mov 

ax,4c00h 

; DOS Exit Pgm Command 


int 

21h 



jmp 

ShowCwd 


ShowUsage 

label 

near 



mov 

dx,offset sUsage 

; usage string 

DisplayMsg 

label 

near 



mov 

ah,09h 

; DOS Printstring Command 


int 

2 lh 



jmp 

exit 



.DATA 



sUsage 

db 

"CDD: Change Drive and Directory",13,10,10 


db 

"FORMAT: CDD [Dri 

ve:][Directory]",13,10,10,"S" 

sBadDirl 

db 

'Invalid path "$' 


sBadDir2 

db 

8,,13,10, 


sBadDrive 

db 

1 Invalid drive " 1 


cDrive 

db 

, a:" 1 ,13,10, , $ 1 


sPath 

db 

128 dup (?) 

; current working directory 


end 

main 


; End of File 





Listing 4 status.cpp 


lifndef WIN31 
Idefine WIN31 
lendif 

linclude <string.h> 
linclude <static.h> 
linclude "status.h M 

Idefine TEXTLEN 20 //Really should set this dynamically 

Idefine ixBorder 3 

Idefine iyBorder 3 

Idefine iTextOffset ixBorder+1 

//Paint the control in the current font, adding a 3D textured border 
//Note that OWL does not call Paint routine for a predefined control, 
//so we have to catch WM_PAINT 
void TStatus::WMPaint(RTMessage /*msg*/) 

{ 

PAINTSTRUCT ps; 

RECT rect; 

TEXTMETRIC tmCurFont; 
char text[TEXTLEN]; 

HFONT hCurFont; 

HBRUSH hGrayBrush; 

HPEN hPen, hOldPen; 

LOGBRUSH IbrushGray; 

//Get the current font for control 

hCurFont*(HFONT)SendMessage(HWindow, WM_GETFONT, 0, 0); 
BeginPaint(HWindow, &ps); 

//Set Background to not erase our gray rectangle with text frame 
SetBkMode(ps.hdc, TRANSPARENT); 

GetClientRect(HWindow, &rect); 

hGrayBrush*(HBRUSH)GetStockObject(LTGRAYBRUSH); 

SelectObject(ps.hdc, hGrayBrush); 

Rectangle(ps.hdc,rect.left, rect.top, rect.right+1, rect.bottom+1); 
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same arguments you would for a TStatic object for the static 
text control. Listings 6 ( test.cpp ), 7 ( test.h ), 8 ( test.rc ), and 

Listing 4 continued 


hPen“(HPEN)GetStockObject(WHITE_PEN); 
h01dPen*(HPEN)Select0bject(ps.hdc, hPen); 

MoveTo(ps.hdc, rect.left+ixBorder, rect.bottom-iyBorder); 

LineTo(ps.hdc t rect.right-ixBorder, rect.bottom-iyBorder); 

LineTo(ps.hdc, rect.right-ixBorder, rect.top+iyBorder); 

hGrayBrush*(HBRUSH)GetStockObject(GRAY_BRUSH); 

GetObject(hGrayBrush, sizeof(lbrushGray), &lbrushGray); 

//use color of stock gray_brush(there is no gray_pen) 
hPen*CreatePen(PS_SOLID, 0, IbrushGray.IbColor); 

SelectObject(ps.hdc, hPen); 

MoveTo(ps.hdc, rect.right-ixBorder, rect.top+iyBorder); 

LineTo(ps.hdc, rect.left+ixBorder, rect.top+iyBorder); 

LineTo(ps.hdc, rect.left+ixBorder, rect.bottom-iyBorder); 
SelectObject(ps.hdc, hOldPen); 

DeleteObject(hPen); 

SelectObject(ps.hdc, hCurFont); //Use current font 
GetTextMetrics(ps.hdc, AtmCurFont); 

GetText(text, TEXTLEN); 

TextOut(ps.hdc, rect.1eft+iTextOffset, 

((rect.bottom-rect.top)-tmCurFont.tmHeight)/2+rect.top,text, 
strlen(text)); //Prints Text In Middle y, 

//and iTextOffset away from left border 
EndPaint(HWindow, &ps); 

}; 

void TStatus::WMSetText(RTMessage msg) { 

//toggle WS_VISIBLE before calling Default WNDPROC so static text is not redrawn 
//before we get a chance to redraw it. 

SetWindowLong(HWindow, GWLJTYLE, GetWindowLong(HWindow, GWL_STYLE)^WS_VISIBLE); 
DefWndProc(msg); //Allow Default WNDPROC a chance to set text 
//Make VISIBLE again 

SetWindowLong(HWindow, GWLJTYLE, GetWindowLong(HWindow, GWL_STYLE)^WS_VISIBLE); 
InvalidateRect(HWindow, NULL, TRUE); //Invalidate whole window 
UpdateWindow(HWindow); //Force a redraw (So we only draw after a WM_PAINT 

} 

// End of File 


Listing 5 status, h 


linclude <static.h> 

_CLASSDEF(TStatus) 
class TStatus : public TStatic 
{ 

public: 

TStatus(PTWindowsObject Parent, int Resourceld, WORD ATextLen, 
PTModule AModule=NULL) : 

TStatic(Parent, Resourceld, ATextLen, AModule){); 
virtual void WMPaint(RTMessage msg)«[WM_FIRST+WM_PAINT]; 
virtual void WMSetText(RTMessage msg)-[WM_FIRST+WM SETTEXT]; 

}; 

/* End of File */ 


Listing 6 test.cpp 


linclude <dialog.h> 
linclude <string.h> 
linclude <static.h> 
linclude "status.h" 
linclude "test.h" 

Idefine APPNAME "Test" 

Idefine BUFSIZE 20 

class TTest : public TDialog 

i 

public: 

TTest; 

TTest(); 

virtual void Buttonl()-[ID_FIRST+IDl] 
virtual void Button2()-[ID FIRST*ID_2] 
virtual void 8utton3()-[ID _ FIRST+ID_3] 
PTStatic PTETest; 

); 


TTest::TTest() : TDialog(NULL, APPNAME) 

{ 

PTETest=new TStatus(this, IDJTest, BUFSIZE); 
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Listing 6 continued 


) 

void TTest::Buttonl() 

{ 

PTETest->SetText("Pressed button 1"); 

) 

void TTest::Button2() 

{ 

PTETest->SetText("Pressed button 2"); 

} 

void TTest::Button3() 

{ 

PTETest->Clear(); 

} 

class TTestApp : public TApplication 

{ 

public: 

TTestApp(LPSTR AName, HANDLE hInstance, HANDLE hPrevInstance, LPSTR lpOnd, int nOniShow) 
: TApplication(AName, hlnstance, hPrevInstance, lpCmd, nCmdShow) {} ; 
virtual void InitMainWindow(); 

}; 

void TTestApp::InitMainWindowQ 

{ 

MainWindow ■ new TTestQ; 

} 

int PASCAL WinMain(HANDLE hlnstance, HANDLE hPrevInstance, LPSTR lpCmd, int nCmdShow) 

{ 

TTestApp TestApp(APPNAME, hlnstance, hPrevInstance, lpCmd, nCmdShow); 

TestApp.Run(); 
return TestApp.Status; 

} 

// End of File 


9 ( test.def) construct a dialog box with three buttons: two of 
the buttons write to the status line and the third one clears it. 
The make file (for Borland C++ 3.1) is shown in Listing 10 
(test.mak). 


Listing 7 

test.h 

Idefine ID 1 

101 

Idefine ID 2 

102 

#define ID 3 

103 

#define ID Test 

100 

/* End of File 

*/ 


Listing 8 test.rc 


linclude "test.h" 

Test DIALOG 41, 41, 109, 69 

STYLE DS_L0CALEDIT | WS_0VERLAPPED | WSVISIBLE | WS_CAPTI0N | WS_SYSMENU 
CAPTION "Experimental Status Line" 

FONT 10, "Arial" 

BEGIN 

LTEXT "This is my text!", ID_Test, 0, 58, 109, 11, WS_CHILD | WS_VISIBLE | WS_GR0UP 

PUSHBUTTON "Button2", ID_2, 54, 24, 48, 14, WS_CHILD | WS_VISIBLE | WS_TABSTOP 

PUSHBUTTON "Clear", ID_3, 79, 40, 24, 14, WS_CHILD | WS_VISIBLE | WS_TABSTOP 

PUSHBUTTON "Button1", ID_1, 54, 7, 47, 14, WS_CHILD | WS_VISIBLE | WS_TABSTOP 

END 
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Listing 9 

test.def 


; TEST.DEF module definition file 

NAME 

test 

DESCRIPTION 

EXETYPE 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKSIZE 

'Status line demo' 

WINDOWS 

'WINSTUB.EXE' 

PRELOAD MOVEABLE DISCARDABLE 

PRELOAD MOVEABLE MULTIPLE 

1024 

8192 


As you can see, all I did was redefine the response for two 
messages, WM_PAINT and WMJETTEXT. One thing to note is that 
I clear USVISIBLE before passing UMJETT EXT to DefUndProc. 
The problem with subclassing controls is that they tend to 
draw themselves before you get a chance to draw them, 
which usually causes a very noticeable flicker. But if I clear 
USJISIBLE first, the static text control’s own WMJETTEXT 
response does not draw itself. The only routine that draws the 
control is my UM_PAINT routine and there is no flicker. 

One last note: the more portable way to add a status line 
control would be as a custom control in a DLL. As it turns out, 


Listing 10 test.mak 


# . 

# TEST.MAK make file 

# . 

WINLINK*tlink /c /n /Tw /Ld:\bc\owl\1ib;d:\bc\classlib\lib;d:\bc\lib cOws 
WINLIB«import mathws cws 
WINCObcc -c -w-par -P -W -2 
WINROrc -r -id:\bc\include 

test.exe : test.obj status.obj test.def test.res 

S(WINLINK) test status, test, NUL, $(WINLIB) owlws tclasss, test 
rc -t test.res 

test.obj : test.cpp 

S(WINCC) -IS(INCLUDE) -DWIN31 test.cpp 

status.obj : status.cpp 

$(WINCC) -IS(INCLUDE) -DWIN31 status.cpp 

test.res : test.rc 
S(WINRC) test.rc 


most of the unique code is the response to window mes¬ 
sages, which is all I had to write for the status line (see List¬ 
ings 4 and 5). Even if you plan to write a custom control, you 
may find it helpful to prototype it as an OWL class. All it 
would take to turn the above code into a custom control is to 
create the underlying static control and subclass it, and to 
write the dialog boxes for editing that are required by 
Resource Workshop or the SDK tools. □ 
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Windows/DOS 

□ DEVELOPER'S JOURNAL 

New Products 

Industry-Related News & Announcements 


Origin Provides Graphic Support Via DDE 

Origin is a technical graphics and data analysis applica¬ 
tion for Windows, specializing in providing high quality scien¬ 
tific and technical graphs for publications and presentations. 
Origin provides a DDE interface to Labtalk (a scripting lan¬ 
guage), making it accessible from Visual Basic v3.0 and other 
languages that can communicate via DDE. Origin supports 
multiple graph types, including line, scatter, column, bar, 
area, error bars, hi-lo-close, spline, step, box, histogram, X 
bar Ft(QQ, polar, and waterfall plots. Origin supports 3D 
graphics with a separate 3D/Contour module, including 3D 
scatter, trajectory, filled surface, color map surface, wire 
frame, 3D bar, ribbon and wall charts, color-filled contour, 
and labeled contour plots. 


You can examine and manipulate realtime data with 
Origin's interactive tools. Enlarger is a tool for zooming in to 
examine details of the incoming data, Data Reader lets you 
pick values from individual data points, and Data Selector 
lets you select a region of the data for operations such as 
linear regression. Origin contains statistical and mathemati¬ 
cal functions, including linear, polynomial and multiple 
regressions, non-linear curve fitting to common and user- 
defined functions, t-Test, ANOVA, data smoothing, integrate, 
differentiate, EFT, and more. 

Origin costs $495; the 3D and Contour module costs $125: if 
purchased together, the cost is $545. For more information, 
contact MicroCal Software, Inc., 22 Industrial Drive East, Nor¬ 
thampton, MA 01060, (413) 586-2013; FAX (413) 586-0149. 


3d Graphic Tools v3.11ncludes 32-Bit Support 


Micro System Options has released a new version of 3d 
Graphic Tools, a general purpose set of more than 200 three- 
dimensional object manipulation, color drawing, and render¬ 
ing functions for Visual Basic v3.0 and C/C++ developers who 
want to create CAD, CAM, scientific, engineering, animation, 
multimedia, data visualization, and related applications. The 
new version features performance enhancements, using 32- 
bit, fixed-point math on 80386 or better processors. The new 
version also uses an internal memory suballocator to reduce 
the calls to Windows memory management and increase 
the data capacity of the product 

The package supports surface plots, contour plots, hid¬ 
den surface removal, texture and bump mapping, flat or 
Phong shading, z-buffering, color lighting, write frames, line 


drawing, annotations, grids and more. You can create ob¬ 
jects using external data or internal primitives, or as 
parametric mesh surfaces through extrusion, rotation, and 
deformation operations. The package includes common poly¬ 
nomial interpolation methods for curve and surface genera¬ 
tion. You can route the device-independent output to 
standard device contexts, including metafiles, graphics 
printers, and plotters. 3d Graphic Tools supplies both VBX 
and DLL API interfaces. 

3d Graphic Tools for Visual Basic costs $95. The C and C++ 
versions, including complete source code, cost $295. For 
more information, contact Micro System Options, P.O. Box 
95167, Seattle, WA 98145-2167, (206) 868-5418. 


MKS RCS v6.1 Available for Windows 

Mortice Kern Systems has released MKS RCS v6.1, a 
revision control system which now supports Windows 3.1 to 
provide a graphical user interface in addition to its com¬ 
mand-line interface. MKS RCS offers security for distributed 
project development environments and includes an encryp¬ 
tion facility. The system includes unlimited branching, merg¬ 
ing, file comparison, report generation, symbolic names, log 
file compression, network support, and locking. The system 


is also compatible with UNIX, aiding cross-platform develop¬ 
ment. MKS RCS also includes MKS Make, an automatic con¬ 
figuration builder that works with most popular PC compilers. 

MKS RCS v6.1 for Windows costs $349; upgrades cost 
$99. For more information, contact Mortice Kern Systems, 
Inc., 35 King Street North, Waterloo, Ontario, Canada N2J 
2W9, (519) 884-2251; FAX (519) 884-8861. 
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Software Tutor for Microsoft Exam 

Transcender Corporation has released Examinator, an in¬ 
teractive Windows training program that helps you study for 
and pass Microsoft's Windows certification examinations in 
order to become a Microsoft Certified Professional. Ex¬ 
aminator lets you take four complete simulated exams. The 
program analyzes your responses and explains the reasoning 
behind each answer. The detailed scoring reports point out 


the areas you should emphasize in your studies. Besides the 
four exams, the package includes instructions for becoming 
certified, study outlines, and a complete guide to preparing 
for the examinations. 

Examinator costs $93. For more information, contact 

Transcender Corporation, 242 Louise Avenue, Nashville, 
TN 37203-1812, (615) 327-1858; FAX (615) 320-6594. 


TCP/IP Toolkit Update Is Easy on RAM 

The Distinct TCP/IP Software Development Kit is a net¬ 
working package for Windows developers and end users. Be¬ 
sides the new Windows Sockets API, it includes support for 
Ethernet, Token Ring, FDDI, ISDN, SLIP, CSUP, and PPP. It is 
compatible with Microsoft Lan Manager, Banyan Vines, 

Novell Netware, and DEC Pathworks, by virtue of its support 
for Packet, ND1S, and ODI drivers. The Distinct TCP/IP protocol 
stack is a Windows DLL designed to use as little memory as 
possible; it can open as many as 128 concurrent sockets. 

Distinct TCP/IP now supports Visual Basic v3.0 and in¬ 
cludes custom controls that allow Visual Basic programmers 


to establish connections, read and write data, and transfer 
files. Visual Basic programmers can also use the package to 
access APIs for Berkeley Sockets, Telnet, and NetWin. 

The Distinct TCP/IP for Windows SDK v3.1 costs $495 for 
the Standard Edition and $695 for the Professional Edition 
(the latter includes the Distinct Telnet and Distinct FTP and 
TFTP applications). For more information, contact Distinct 
Corporation, 14395 Saratoga Avenue, Suite #120, 
Saratoga, CA 95070, (408) 741-0781; FAX (408) 741-0795. 


Updated Help Magician Supports WinHelp 3 .1 Features 


The Windows Help Magician is a tool for creating Win¬ 
dows help (.hip) files. Unlike many of its competitors, Help 
Magician does not require Microsoft's WinWord to generate 
the Rich Text Format (. rtf) files needed as input to the 
Microsoft help compiler. The product provides a single, in¬ 
tegrated environment for creating and editing help text, test¬ 
ing the resulting hypertext system, and compiling and 
executing the final .hip file product. The product also lets 
you automatically reference multiple occurrences of words 
or phrases as jumps or popups. 

The new version of Help Magician supports the features 
added to the Windows 3.1 help engine, including secondary 


windows, non-scrolling regions, background colors, advanced 
paragraph formatting, macros, jumps to other help Files, help 
window sizing and positioning, as well as custom copyright 
strings, icons, and buttons. Help Magician v2.0 also removes 
memory limitations of the previous version of the product 
The Windows Help Magician v2.0 costs $199 for one user, 
$495 for two to six networked users, or $995 for seven to 
twelve networked users. For more information, contact 
Software Interphase, 82 Cucumber Hill Road, Suite 140, 
Foster, Rl 02825, (800) 54-BASJC or (401) 397-2340; FAX 
(401)397-6814. 


NetManage TCP/IP Offers VB 3.0 Support 

NEWT-SDK is a development kit for developing network 
applications. The product now provides a Visual Basic inter¬ 
face to the TCP/IP API. As a protocol stack, NEWT is a Win¬ 
dows DLL that requires 6Kb of base memory and provides 
up to 64 concurrent sessions. The product also supports the 
Windows Sockets API and includes over 300Kb of com¬ 
mented sample source code. 


The NEWT-SDK for TCP/IP costs $500 and includes support 
for either a Berkeley 4.3 BSD Socket API or the Windows 
Sockets API. An optional RPC SDK is also available for support¬ 
ing distributed applications based on ONC RPC/XDR. For more 
information, contact NetManage, Inc., 20823 Stevens Creek 
Blvd., Cupertino, CA 95014, (408) 973-7171; FAX (408) 257- 
6405. 


Updated RoboHELP Taps WinHelp v3.1 Features 


RoboHELP is a Word for Windows add-on that helps 
developers create and maintain Windows help (.hip) files. 
The new version provides access to the new features of the 
Windows 3.1 help engine, such as secondary windows, and 
built-in macros. The new version can automatically convert 
existing text into a help system, or a help system into user 
documentation. The package now includes a custom control 
that supplies a help button for dialog boxes in your applica¬ 
tion. The integrated environment lets you handle all aspects 


of help file creation (including compiling and running the 
help file and maintaining the help project file) from within 
RoboHELP/WinWord. The product can detect potential errors 
before compiling, taking you to the exact location of the 
problem. 

RoboHELP v2.0 costs $495; upgrades cost $199. For more 
information, contact Blue Sky Software Corporation, 7486 
La Jolla Blvd., Suite 3, La Jolla, CA 92037, (800) 677-4WIN 
or (619) 459-6365; FAX (619) 459-6366. 
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VBIite Augments VB 3.0 Programming 

VBIite is a programming library that provides B-Tree in¬ 
dices, communications, and dynamic printer control to Visual 
Basic v3.0 (VB) programmers. The package also includes 30 
array sort, search, and manipulation routines. 

VBIite's printer control supplies a printer interface to 
your VB application that allows setup changes (such as 
portrait to landscape) while the program is printing. You can 
make changes using VB properties or via interactive dialog 
boxes. You can also print bitmaps, line graphics, and text at 
any location on the page. 

VBIite's communication DLL offers low-level serial port 
control such as on-the-fly baud rate changes without drop¬ 


ping carrier. The DLL lets you read and write all serial lines 
(such as DTR), replace bad characters, handle nonstandard 
EOF characters, and provide XON/XOFF control and hardware 
handshaking. 

VBIite's indexing lets you create and update B-Tree in¬ 
dexes. You can index any expression and create condition in¬ 
dexes that only include selected records. The index file is 
independent of any database file format 

VBIite costs $149 and requires no royalties. For more in¬ 
formation, contact TeraTech, 100 Park Avenue, Suite 360, 
Rockville, MD 20850, (800) 447-9120 or (301) 424-3903; 
FAX (301) 762-818S. 


Custom Control Provides Speech Recognition 


SPOT/VBX is a new custom control that gives Visual C++ 
and Visual Basic programmers access to the Speech Systems 
PE400 Turbo Board in order to add speech recognition fea¬ 
tures to Windows applications. PE400 applications can use 
an external hand-held button, foot-pedal button, or no but¬ 
ton at all. PE400 applications can incorporate a rejection 
scheme tuned to detea invalid user utterances; the applica¬ 
tion can then prompt the user to repeat the utterance. The 
PE400 SDK can generate applications with built-in funaions 
for playing sounds and prompts via sound boards to provide 
user feedback. The SDK also includes ProWav, a produa that 


lets applications play back strings of text whose words are 
stored in a diaionary of WAV files. These tools let you create 
applications that let the user and computer literally talk to 
each other. 

SPOT/VBX comes with the Speech Systems PE400 System 
Development Kit and costs $1,495; the PE400 Turbo Board, 
microphone, and runtime software cost $3,495. For more in¬ 
formation, contaa Speech Systems, Inc., 2 888 Bluff Street, 
Suite 334, Boulder, CO 80301-9002; (303) 449-0481; FAX 
(303)447-9241. 


RT-DBMS Available as DLL 

RT-DBMS is a memory-resident database system 
designed to efficiently handle the loading and storage of a 
permanent database system as a non-intrusive background 
task. It uses a client/server architeaure and supports multi¬ 
ple independent clients with a single database server. The 
database supports both relational and network data models. 
The network model lets you create relationships between 
records without storing unique keys in those records. The 
package includes a data definition language precompiler, where 
the data definition language is patterned after C structures. 


RT-DBMS is now available with a DLL interface, making it 
compatible with Visual Basic v3.0. The system was already 
available under UNIX. A database built with RT-DBMS under 
UNIX can be brought to Windows and accessed from Visual 
Basic. The database is written entirely in C and is fully C++ 
callable. 

RT-DBMS costs $495. For more information, contaa Omni- 
Soft, Inc., 1183 Bordeaux Drive, Suite IS, Sunnyvale, CA 
94089, (408) 747-0878; FAX (408) 747-1796. 


Fast Text Search Available for Visual Basic 


FAST TEXT SEARCH (FTS) for C/Windows is a library that 
can add full text search capabilities to Windows applications. 
By creating and maintaining proprietary index files, FTS for 
C/Windows can rapidly search large amounts of both struc¬ 
tured and unstruaured data for any charaaer strings. The 
library supports LANs and multi-user access, and can be in¬ 
tegrated with third-party file handlers such as CodeBasic and 


Apex Agility/VB. Available as a Windows DLL, the library sup¬ 
ports development in Visual Basic v3.0. 

FTS for C/Windows costs $189 and comes with a 30-day 
guarantee, documentation, and sample applications. For 
more information, contaa Index Applications Incorporated, 
Suite 208, 85 46 Broadway, San Antonio, TX 78217, (210) 
822-4818; FAX (210) 828-5074. 


New Tool Provides Image Manipulation for VB v3 


/M4GFBASIC is a set of four custom controls for Visual 
Basic and Visual C++: a display control, an OCR control, a scan¬ 
ning control, and a scanning postprocessor control. The dis¬ 
play control decompresses, displays, zooms, and rotates 
image data on the screen. The OCR control can recognize 
text by field, or by seleaing areas interaaiveiy with the 
mouse. The scanning control supports more than 60 popular 


scanners to provide scanned image input ScanFix cleans up 
image data, reducing file size by as much as 40 percent. 

Each IMAGEBASK control costs $895; all four together cost 
$2,995. For more information, contaa Diamond Head 
Software, 707 Richards St, Suite 630, Honolulu, HI 96813, 
(808) 545-2377; FAX (808) 599-3769. 
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M.4 Brings Knowledge Base to VB and VC 

Cimflex Teknowledge Corporation has released M.4 v3.0 
for DOS and Windows. The product lets Visual Basic v3.0 
programmers add knowledge base abilities to their applica¬ 
tions. The package includes a custom control for Visual C++ 
access, a DDE server interface for Asymetrix's ToolBook, and 
callable libraries for DOS and Windows. The package in¬ 
tegrates both procedural control and object-oriented 


programming in a knowledge base development environ¬ 
ment and language. 

M.4 v3.0 costs $995. For more information, contact 

Cimflex Teknowledge Corporation, 1810 Embarcadero 
Road, Palo Alto, CA 94303, (415) 424-0500; FAX (415) 493- 
2645. 


Access Xbase Data with CodeBasic vS.Ofor VB 


CodeBasic v5.0 is a library for Visual Basic v3.0 that 
provides XBase database access and lets applications share 
data, index, and memo files with concurrently running 
dBASE, FoxPro, and Clipper applications on a network. The 
new version features CodeReporter, an interactive relational 
report writer for developers. By analyzing index information 
to avoid retrieving records not in the query solution set, the 
new version provides increased performance, querying a 


500,000-record file in less than a second on a 25Mhz 80386. 
The package also uses memory optimization and buffering 
to further improve performance and reduce network loading. 
CodeBasic v5.0 costs $195. For more information, contact 

Sequ/ter Software, Inc., Suite 209, 9644 - 54 Avenue, Ed¬ 
monton, Alberta, Canada T6E 5VI, (403) 437-2410; FAX 
(403) 436-2999. 


Add Imaging to VB with KIPP Toolkit 

The KIPP Developers Toolkit works with Kofax controls 
that interface to high-end printers and scanners, and allows 
Visual Basic v3.0 programmers to add imaging features to 
their applications. The toolkit supports subsecond image dis¬ 
play, high-speed printing and scanning, and image manipula¬ 
tion features such as scaling, rotation, saturation, picking 
rectangles, and more. The product supports production scan¬ 
ners from Fujitsu, Bell+Howell, and TDC at up to 72 single¬ 
sided pages per minute or 48 dual-sided pages per minute, 
as well as Hewlett-Packard, Fujitsu, Ricoh, Canon, and others 


at up to 22 pages per minute. The toolkit supports TIFF, PCX, 
and user-defined file formats. Built-in compression typically 
reduces image files from about 1Mb per page to under 50Kb 
per page, supporting compression types such as CCITT Group 
3/ID, Group 3/2D, Group 4, and PackBytes. 

The KIPP Developers Toolkit costs $1,495 and is also com¬ 
patible with Microsoft C/C++ for DOS, Windows, and NT. For 
more information, contact Kofax Image Products, 3 Jenner 
Street, Irvine, CA 92718, (714) 727-1733; FAX (714) 727- 
3144. 


FarPoint Updates Spreadsheet VBX Control 


Spread/VBX v2.0 (formerly named Visual Architect) is a 
new version of FarPoint Technologies’ spreadsheet control 
for Visual Basic and Visual C++ programmers. New features 
include optional borders around rows, columns, cells, or cell 
ranges; virtualized database support; selection of multiple 
non-contiguous blocks of cells; text overflow to adjacent 
cells; single or multiple selection listbox support; spin but¬ 
tons within date, time, and integer cells; full sorting support; 
checkbox celltype; right button messages sent to parent; 
owner draw celltype; more parent notification messages; 


combo-box editing; dynamic manipulation of combo-box 
items; new row mode operations-, grid color change; a 4-byte 
user-definable data item per row or spreadsheet; full clip¬ 
board support; changeable default cursor. The date control 
now lets you change the Julian starting date. 

Spread/VBX costs $245. For more information, contact 
FarPoint Technologies, Inc., 585A Southlake Boulevard, 
Southport Office Park, Richmond, VA 23236, (800) 645- 
5913 or (804) 378-0432; FAX (804) 378-1015. 


VBAssist v3.0 Gains VB v3 Enhancements 

Sheridan Software Systems, Inc, has updated VBAssist, 
its add-on tool for Visual Basic. VBAssist V3.0 now provides 
tools for taking advantage of Visual Basic v3.0’s new 
database access extensions. You can use the new version to 
design forms for database applications using drag-and-drop 
operations to link table columns to bound controls. Instead 
of having to update each individual control's data source and 
data field in the properties window, VBAssist’s Data Assistant 
opens a window showing all fields in the database as¬ 
sociated with the bound data control; the developer just 
clicks the mouse on the desired field and drags and drops it 
onto the target control. 


VBAssist’s Form Wizard can generate a form automat¬ 
ically, similar to the way a Wizard works in Access. These 
new features also let developers create and modify table 
structures, and view or modify data for any table. The data 
access tools in VBAssist work with all databases compatible 
with Visual Basic’s data access engine. 

VBAssist costs $179. For more information, contact 
Sheridan Software Systems, Inc., 65 Maxess Road, Mel¬ 
ville, NY 11747, (516) 753-0985; BBS (516) 753-5452; FAX 
(516)753-3661. 
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BRIDGIT Gives VB dBase/Clipper Access 

BR1DGIT is a database engine that provides a program¬ 
ming interface between Visual Basic v3.0 and dBase or Clip¬ 
per databases. The package lets you open, position, read, 
and write both dBase and Clipper files, and also supports in¬ 
dexing, seeking, and one-to-many relationships. The package 


supports both single and multiple users and requires no 
royalty fees. 

BRIDGIT costs $69.95. For more information, contact Un- 

elko Corporation, 7428 East Karen Drive, Scottsdale, AZ 
85260, (602) 991-7272 ; FAX (602) 483-7674. 


Online Service Caters to VB Programmers 

VB/Online is an online information service dedicated to 
Visual Basic v3.0. The service provides hundreds of Files, a 
messaging system, books on Visual Basic, and all commercial 
software related to Visual Basic. A membership fee gives 
you access to freeware, shareware, demonstration 
programs, tips, tricks, and helpful information. Every book on 
programming with Visual Basic is available for sale, along 
with reviews of each title. You can also purchase software 


through the service. Members receive discounts on books 
and software. 

VB/Online charges a yearly membership fee of $39.50. 
For more information, contact VB/Online Information Ser¬ 
vice, a division of Book Stacks Unlimited, Inc., 200 Public 
Square, Suite # 26-4600, Cleveland, OH 44114-2301, (216) 
861-0467; modem (216) 694-5734. 


VB Compress Squeezes Visual Basic Executables 


VB Compress v2.1 is a tool for Visual Basic v3.0 that com¬ 
bines project analysis, cross-referencing, optimization, and 
debugging capabilities into a single integrated tool. When 
you click the name of a Visual Basic project, VB Compress 
analyzes the code in all project files and identifies every un¬ 
referenced variable, constant, type definition, API and DLL 
declaration, subroutine, and function procedure. Then VB 
Compress creates an optimized copy of the code, instructing 
Visual Basic to generate a new . exe file, without unnecesary 
code or data. The optimized executable has no overhead from 


using standard headers or libraries and none of the duplicate 
or obsolete code that creeps in during development 

The Professional version of VB Compress includes more 
sophisticated optimization and debugging capabilities, such 
as an equivalent to the C assert () macro, compression of 
embedded string literals, automatic identification and ex¬ 
clusion of debugging code, and more. 

VB Compress v2.1 costs $59.95 for the Standard Edition, 
or $99.95 for the Professional Version. For more information, 
contact Tailored PC's, 20 Cedar Street, Charlestown, MA 
02129, (617) 242-2511; FAX (617) 241-8496. 


SMITHWARE Enhances VB Btrieve Access 

SMITFIWARE Visual Controls for Btrieve is a new package 
that helps Visual Basic v3.0 programmers access Btrieve 
(Novell) databases. Like the new data access controls in 
Visual Basic v3.0, Visual Controls for Btrieve lets program¬ 
mers design database applications and link them to Btrieve 
tables by selecting property values. The package contains 
everything necessary to maintain Visual Btrieve Databases, 
including the Btrieve DLL and DDF Builder for Windows. 

Visual Controls for Btrieve is based on VAccess controls, 
which are placed on Visual Basic forms and point to Visual 


Btrieve Database tables. The custom text box, check box, op¬ 
tion button, list box, combo box, picture box, scroll bar, and 
command button controls are all bound to a VAccess control 
and linked to fields from its database. Experienced Btrieve 
developers can access all Btrieve parameters via properties 
of the VAccess control. 

Visual Controls for Btrieve costs $249.95. For more infor¬ 
mation, contact SMITHWARE, Inc., 1052 Madison Square, 
Madison, TN 37115, (615) 860-3500. 


Raima Announces Database Server 

Raima Database Server is a new client-server database 
that provides high throughput transaction processing, sup¬ 
port for multiple APIs, and compliance with industry stand¬ 
ards, including ANSI SQL, SQL Access Group Call Level 
Interface (SAG CLI), and Microsoft’s Open Database Connec¬ 
tivity (ODBC). ODBC compliance simplifies connectivity be¬ 
tween Database Server and Visual Basic v3.0, as well as 
other third-party tools such as report writers, 4GLs, and 
screen packages. The server features declarative referential 


integrity, fault tolerance, and transaction processing. Perfor¬ 
mance is enhanced with Relational Accelerator Extensions, 
including a create join statement that lets you create 
direct one-to-many relationships. 

Raima Database Server prices start at $1995 and include 
a Windows-based administration utility. For more informa¬ 
tion, contact Raima Corporation, 160 5 NW Sammamish 
Road, Suite 200, Issaquah, WA 98027, (206) 557-0200; 
(206) 557-5200. 


Create Btrieve DDF files with Visual DDF for Btrieve 


Visual Basic v3.0 lets programmers attach, import, and 
manipulate standard Btrieve files from within Visual Basic To 
use these features, you must have the data dictionary files 
(DDF) for the Btrieve files. Without the DDF files, you cannot 
attach or import Btrieve files. Visual DDF for Btrieve lets you 
decipher and map any standard Btrieve file and then create 
the DDF files for use with Visual Basic You can open any 
standard Btrieve file and review the file specifications, such 
as the number of records on file, record length, number of in¬ 


dexes, and page size. Each index is automatically analyzed, 
showing you each segment and its associated data type. 

You can retrieve and display individual records in the file 
along any of the standard index paths, and analyze and map 
individual records on a byte-by-byte basis. 

Visual DDF for Btrieve is available for an introductory 
price of $89.95. For more information, contact Prodata Inc., 
12101 Menaul Blvd NE, Albuquerque, NM 87112-2403, 
(505) 294-1530. 
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Readers' Forum 


Hi Ron, 

I enjoyed your article in the August issue of WDDJ. It's good 
to know other people have some of the same troubles I had 
when I first started using C++. Anyway, I thought I'd share a 
trick I picked up somewhere along the way relating to con¬ 
structors that fail. I spent several years as a C programmer 
before jumping into C++, so I am very comfortable checking 
for a NULL after a mallocO or fopen(). It used to be frustrating 
when a constructor wouldn’t give some indicator of success or 
failure! Then, as I was browsing the source for a C++ library 
we purchased (I wish I could remember which one so I could 
give them proper credit!), I found a mysterious code fragment: 

File *myFile = new File("junk.txt", “r+"); 
if (myFi1e) 

{ 

}" 

"How in the world could that work?" I wondered. I pulled out 
my trusty copy of ARM, and under section 6.4.1, it says: 

“The expression must be of arithmetic or pointer type or of 
a class type for which an unambiguous conversion to arith¬ 
metic or pointer type exists." 

Aha! That’s the trick! If you overload an arithmetic or 
pointer type conversion operator for the class, you can test it 
for failure! In your example from WDDJ, you might try some¬ 
thing like: 

class File 
{ 

II... 

operator int() {return (Handle != NULL);} 

II... 

}; 

This creates a conversion to an integer, allowing the “if” state¬ 
ment to test the class! The beauty of this overload is that it 
works whether the object is instantiated off the stack or off 
the heap. For example: 

II... 

File localObjectC'Junkl.txt 11 , "r+"); 

File *heapObject = new FileC'JunkZ.txt 11 , "r+"); 

II... 

if (1 ocalObject) 

{ /*...*/ } 
if (*heapObject) 

{ /*...*/ } 

While I’m typing, I've got some suggestions for future Prac¬ 
tical C++ topics. I’ve often thought about writing an article on 
C++ streams, but the more I contemplated it, the more I 


thought someone else should write it. The topic is complex, 
and it seems each vendor has their own opinion on how 
streams should be implemented. I wrote a class for printing to 
the Windows print manager using Borland C++ (it’s in Borland’s 
C/C++ Advanced Windows forum, OWSTREAM.ZIP, if you're in¬ 
terested), but decided it would be too much work to translate 
it to Microsoft C++. Anyway, another topic might be practical 
uses for the new .* and ->* operators in C++. I haven’t seen 
these operators used by anybody! Why are they there! 

I’m looking forward to more C++ articles in WDDJ. Keep up 
the good work! 

Pat Weber 
Eveready Battery Company 
Technical and Engineering Applications 
Cleveland, OH 

Excellent point — / didn’t think of using an integer con¬ 
version in this context. I’m generally leery of type conver¬ 
sions (especially to int) since they can create a class of er¬ 
rors the compiler can no longer detect, but for something as 
simple as a File object I might be willing to risk it. I avoided 
streams for a long time because of the lack of stand¬ 
ardization, but recently used them in a project. I discovered, 
as you point out, lack of standardization is still a problem. 
The primary author of the streams package is supposed to 
have a book coming out soon, and I’m hoping that will pro¬ 
vide a rigorous enough definition to start to push vendors 
toward a standard interface. 

As for the operators for dereferencing pointers to mem¬ 
ber functions, .* and - >*, they arise (in my code, anyway) in 
some of the same problems that pointers to functions do. 
For example, I implemented an opcode interpreter in C+ + a 
while back in which each instruction consisted of a 1-byte 
opcode followed by a 2-byte argument. The main loop just 
fetched the opcode and argument, used the opcode as an 
offset into a table of function pointers, then called the func¬ 
tion and passed it the argument. Flowever, I wanted these 
“opcode functions" to be member functions of the class that 
implemented the rest of the interpreter, so that they had ac¬ 
cess to things like the interpreter’s variable stack. That 
called for pointers to member functions instead of pointers to 
functions, and my opcode loop ended up looking something 
like this: 

extern TInterp Interp; 

int (TInterp::*OpFunc)(int Arg); 

for(;;) 

{ 

int Opcode « Interp.FetchOpcodeO; 
int Arg = Interp. FetchArgO ; 

OpFunc = OpcodeTable[Opcode]; 

(Interp.*0pFunc)(Arg); 

} 
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Thanks for pointing out yet another approach to construc¬ 
tors that can fail, -rib 


To: ronb@rdpub.com 

Subject: Visual Implementation Grouped Menu Items errata 

A minor point perhaps, but hBmp should be NULLed in 
DeleteCheckMenuItemGroupBitmapO. otherwise, multiple calls 
to DeleteCheckMenultemGroupBitmapO cause problems with 
Windows, and calls to CheckMenuGroup after DeleteCheck- 
MenuItemGroupBitmapO will misbehave. These problems 
would most likely occur if this code were in a DLL where mul¬ 
tiple applications were using grouped menu items, since only 
one instance of hBmp would be shared among the apps. If 
each app were careful to call DeleteCheckMenultemGroup- 
BitmapO when it teminated, it would spoil hBmp for all the 
others. 

Max Arai (Max_Arai@trinzic.com) 
That's a good point; thanks for the correction, —rib 


Dear Ron: 

On behalf of the Windows RT Sysops, we're proud to be a 
point for distribution of the Windows/Dos Developers Journal code 
disk. It is an honor to be affiliated with a fine magazine like yours. 

I'd like to invite your reader to join us on GEnie. As of July 
1st, GEnie is only $3.00 per hour, non prime time access. To 
sign up for The Windows RT on GEnie, set your communica¬ 
tions software for half duplex (local echo) at 300, 1200 or 2400 
baud. Dial toll free 1-800-638-8389 (in Canada, call 1 -800-387- 
8330) and enter HHH upon connection. At the U#= prompt, 
enter XTX98354,GENIE and press "enter”. For more information 
about GEnie rates and services, call GEnie customer service at 
1-800-638-9636. The Windows RT has an area set up for 
progammers, all the way from Visual Basic to the DDK. We 
welcome any and everyone to it. We feel the addition of the 
Windows/DOS Developers Journal code disk to our library will 
enhance the way we can help our users. 

Sincerely, 

Rick Ruhl 

Sysop Genie Windows Roundtable 



Developer's 

Marketplace 


SVInstal 

Version 2.0 


--ssfflSsssss* 

Installs anything... 

You just run the install builder, telling it your 
company name, application name, default 
directory, disk space required and list of files. 

No programming or scripts to write. 

What SVInstal does... 

♦ Creates destination directories, copies files. 

♦ Makes program group, puts in your icons. 

Features... 

Progress gauges, multiple source disks, directory 
trees, file compression, network server/client or 
standalone. No royalties! 

Soft Ventures (dept, wdj) nr 

Box 22183 Bankers Hall 

Calgary Alberta Canada (plus $5.00 s&h) 

T2P4J5 (403)278-1681 Canadian $69.95 + 1 % GST 


□ Request 194 on Reader Service Card □ 


1:03 TUB “ is FASTEST! 

RCS" 4.2 

Times are to update a 45K library on a PC/XT. PVCS and TUB 3.0 are 
from Sept 87 PC Tech Journal. MKS RCS 4.2 and TLIB 5.0 are newer. 

TUB™ is BEST! 

“Do not be fooled by the fact that this is the 
least expensive of the five packages reviewed 
here - TLIB has features and power to spare” 
John Rex, Computer Language 
" TLIB is a great system" J. Vallino, PC Tech J 

• Full-Featured Version Control for Software 
Professionals. Check-in/out locking. Branching. 
Keywords. Wildcard and list-of-file support. Can 
merge parallel changes and undo intermediate 
revisions. Network and WORM support. Main¬ 
frame compatible deltas for Pansophic, ADR, IBM, 
etc,. Integrates with Opus " MAKE & Slick " MAKE. 

MS-DOS $139, OS/2 $195 + shipping visa/MC 
5 station LAN license $419 (OS/2 $595), call for other sizes 

BURTON SYSTEMS SOFTWARE 

PO Box 4156, Cary, NC 27519 (919)233-8128 

□ Request 137 on Reader Service Card □ 



Tools for Novell’s Btrieve® 


It.support III Bsupport II 

Bed it 3.0 - Btrieve file viewer/editor. 
Banalyze 2.0 - Btrieve app. debugger. 

Brun 2.2 • BUTIL replacement plus source. 
Bereate 2.0 - file creation utility. 

Bcheck 2.0 - Btrieve file analyzer. 

Xsupport 1.0 - build data dictionary 
(.DDF) for Access, OV, 
Crystal Rpts. 

Xport 2.0 - export/import CDF, SDF, 
dBASE. 

Call for information on additional 
products and FREE demo! 

Information Architects, Inc. pj,., son| 359-2721 
3130 Pine Tree Road (517)887-8000 

Lansing, MI 48911 Fax: (517) 887-2366 


□ Request 120 on Reader Service Card □ 
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HDTI IIUU RELIEF FROM 

ur i Linn linker headaches 


OPTLINK for Windows offers 
Borland-based developers with 
33% faster linking, 33% smaller 
programs, and fully supports 
Turbo Debuger. Links Visual C++ 
programs 50% faster too! 

SLR Systems, Inc. 

(412) 282-0864 • Fax: (412) 282-7965 


□ Request 154 on Reader Service Card □ 



We Understand The 
Programmer's Mind 


When the country's top firms look for the 
best developers available, they turn to 
Bateman. Why? Because we specialize in 
Microsoft Windows, NT, OS/2 and Macin¬ 
tosh recruiting nationwide. So if it's time for 
a career move, give us a call. We under¬ 
stand your skills, and the marketplace for 
them... we understand you. 

□Bateman Inc. 

5847A Uplander Way 
Culver City, CA 90230 
Tel: 310-641-4100 Fax: 310-641 -2900 
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GCP++ is the 
development 
solution for ^SSfi 
TCP/IP under 
Windows! 

Encapsulates TCP, UDP, TELNET & TFTP in a 
robust and easy-to-use server, so you start 
with proven socket library code! 

Genisys Comm Pack++ 

• OLTP, emulators, DBMS, all client/server apps • 
• VB Custom Control and DLL interlaces • 

• Low-cost stack option for integrators • 

Download the GCP++ Evaluation Kit today! 

0 GENISYS Comm, Inc. 

314 S Jay St. Rome. NY 13440 
MlOgOFP 315-339-5502 • tax 5528 

COMPATIBLE" GCP++® GENISYS.com 


□ Request 145 on Reader Service Card □ 


SpyWorks-VB 

For Visual Basic™ - Windows 

SpyWorks-VB allows you to do virtually 
anything in Visual Basic that is possible 
using other languages such as C. It 
includes controls that easily subclass 
VB forms and controls, detect keyboard 
events, and support callback functions. 
SpyWorks includes debugging tools to 
view message and event history, detect 
API parameter errors, Browse Windows 
memory and resources, and retrieve 
information about any window, form or 
control in the system. 

SpyWorks-VB is only $129 + $5 s&h ($15 
outside U S & Canada). Visa/MC orders 
include phone and exp. date. CA residents 
add 8.25% sales tax. Dual media - Requires 
VB2.0 

Desaw are 

5 Town & Country Village #790 

San Jose, CA 95128 

(408) 377-4770 fax:(408) 371-3530 

□ Request 149 on Reader Service Card □ 


Career Marketing Associates 

7100 East Belleview Avenue, Suite 102 
Englewood. CO 80111_ 

Today, 1993 

Dear WINDOWS DEVELOPER: 

Do you know where the best 
Windows development jobs are? I spend 
my time looking for strong 
opportunities for Windows developers 
and software engineers. I might be 
looking for someone with your 
qualifications right now. And there you 
sit in the corner reading a magazine I 
Pay attention, this is your future we 
are talking about. Currently I have 
multiple jobs requiring Windows 
experience, C++, or GUI. If you are 
thinking about a career change, 
shouldn’t you be working with a 
specialist? All fees are paid by the 
company. Write, call, fax, or 
communicate by smoke signals, I’m, 
waiting to hear from you. / 


Sincerely, 



Gary Patton 
303-779-8890 
FAX 303-779-8139 


GENISYS Coiiiin, Inc. 


( ; a 

Windows 

Developer Jobs 

Specialists in jobs for software 
engineers in leading edge technology. 
Windows, PM. GUI, Languages, AI, 

Mac, CASE, Video, Realtime. 

Nationwide contacts with both large 
and small companies including equity 
startups. Many of our clients develop 
and publish commercial software 
products. Managed by graduate 
engineers. Never a fee to an 
applicant. 

1 - 800 - 231-5920 
Scientific Placement, Inc. 



SPI-8, Box 19949, Houston, TX 77224 (713) 496-6100 
SPI-8, Box 71. San Ramon, CA 94583 (510) 733-6168 
SPI-8, Box 4270, Johnson City, TN 37602 (615) 926-6188 
Fax: 713-496-6802 please use Fine Setting on Fax 
Email: Ascii preferred: Internet LSH@Scientific.com; 

iserve: 71250,3001; Genic: D.SMALL6 v 


yCompusf 
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COMI: - COM4: WITH WINDOWSI 

1,2, OR 4 PORT RS-232 BOARDS 
RS-232 AND RS-422 VERSIONS 
XT AND AT INTERRUPT JUMPERS 
OTHER PRODUCTS INCLUDING LAPTOP 
ADD-ONS 

DELIVERY FROM STOCK. 

MADE IN USA 

EXCELLENT TECHNICAL SUPPORT 


SEALEVEL SYSTEMS INC. 
P0 60X830 
UBERTY.SC29657 

803 - 043-4343 


,SEALEVEL 
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Opt-Tech Sort/Merge 


^ New-Version 5 

High performance Sort/Merge/Select 
utility. Run as a stand alone 
utility or CALL as a subroutine. 

Supports most languages and 
filetypes including Btrieve 
and dBase. Unlimited filesizes 
multiple keys and much more. 

MS-DOS, Windows $149 
OS/2, UNIX $249 

Call to order or for free info. 


Opt-Tech Data Processing 
P.O. Box 678 
Zephyr Cove, NV 89448 

. (702) 588-3737 y 
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CDROMs for Work and Play! 


Giga Games CDROM $39.95* 

Over 2700 Games for Microsoft Windows and 
MSDOS. 250 Megs of games plus 150 Megs of 
source. Lots of educational games. July 1993. 
CICA MS Windows CDROM $24.95* 
2518 files of MS Windows programs. Utilities, 
games, source code, programming tools, fonts, 
drivers, icons. April 1993. 

Simtel MSDOS CDROM $24.95* 

650 Megabytes, 9000+ files.Programming tools, 
utilities, editors, education, source 
code and more. May 1993. 

* Shareware programs 
require separate payment 
to authors if found useful. 

1-800-786-9907 orders@cdrom.com 
FAX 1-510-674-0821 

$5 S&H per order (USA Canada Mexico) 

$10 overseas 1 -510-674-0783 AMEX/VISA/MC/COD 
*♦ All our disks are 

unconditionally guaranteed. 

Walnut Creek CDROM 

4041 Pike Lane, Suite D-699 
Concord, CA 94520 
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ABSOLUTELY, 
POSITIVELY, 
NO MORE 

V-ls T iHO, 

E R u OR s/ 


$5/disk, 

one issue per disk 
or ALL of 1992 
or 1991 for $20! 

Call today! 

913-841-1631 

FAX 913-841-2624 


Windows/DOS 

□ DEVELOPER'S JOURNAL 

Suite 200 

1601 West 23rd Street 
Lawrence, KS 66046 



2 ™ 

. 

The Art of Visual Basic Programming ™ 

This amazing new book by J. D. Evans, Jr. unlocks 
the secrets of Windows and Visual Basic 
application design and programming. It explains 
Windows design from a unique and easy to 
understand perspective, Smart Objects, Hybrid 
Objects, Control Coupling, Events, Focus, Event 
Triggering, Visibility, Form and Module Code 
Placement, DLL Parameter Passing, Variable 
Scope, Strings, and Structures are described and 
explained. Enlightening allegories and annecdotes 
make this one of the most unusual and informative 
Windows books ever written. This book is the 
Rosetta stone for Windows and Visual Basic! 


Book: $29.95 Companion Disk: $9.95 

ETN Corporation 

RD4 Box 659 Montoursville, PA 17754-9433 
(717) 435-2202 (Sales) (717) 435-2802 (FAX) 
AMEX/MC/VISA/Check/MO/PO/COD 
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I think you can divide programmers into two classes: 
those who are “plugged in” to the electronic community and 
those who aren’t. The latter are at a growing disadvantage 
because of how quickly things change in our business. 
Being able to tap into the expertise of hundreds of program¬ 
mers worldwide is an asset that's hard to live without, once 
you’ve tried it. I encourage any “unplugged" readers out 
there to check out the electronic options available, including 
GEnie. —rib 


Dear Mr. Burk, 

Today I received your offer to subscribe to Windows/DOS 
Developer's Journal. Unfortunately, I will have to refuse your 
offer because there was no mention of articles regarding OS/2. 
We subscribe to The C Users Journal because we like the tech¬ 
nical "real world” nature of the articles. 

We would probably subscribe to Windows/DOS Developer's 
Journal if it had coverage of OS/2 of the same technical nature 
as your coverage of C in The C Users Journal. 


OS/2 is our operating environment of choice as we feel 
that it has more of a future than does any flavor of Windows. 
OS/2 is certainly a better development environment for 
programmers, no matter what the targeted platform or 
operating system. I encourage you and R&D Publications to 
increase your coverage of OS/2 topics in both Windows/DOS 
Developer's Journal and The C Users Journal. 

Sincerely, 

James Truesdale, Systems Analyst 
4645 LaGuardia 
St. Louis, MO 63134-9906 

Let's see, if you added the complete OS/2 API set to all 
of the Windows API sets (Win 16, Win32, OLE, etc), and the 
DOS INT 21h API, I think that would come to about a million 
functions! No, we have our hands full just covering two 
operating systems right now, so I don't think we’ll be taking 
on a third just yet. You need to get the magazines that have 
“OS/2” in the title — how about IBM OS/2 Developer, which 
you can order from (800) WANT-OS2? —rib 



Developer's 

Marketplace 


BRID GIT™ 

Your Windows & DOS - disconnection 



Bridgit is a full featured database engine that provides 
easy to use functions for creating, reading, updating 
and indexing dBase-lll+ and Clipper files. 

With Bridgit you create your application only once...then 
convert it to Windows or DOS using either dBase-lll+ or 
Clipper files. 

Order the ultimate database engine for Visual Basic 
and Visual C++ for just $69.95. 


Unelko Corporation 

Tel:(602) 991-7272 • Fax:(602) 463-7674 
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CC-RWER 

( for WINDOWS ) 


SOURCE ANALYSIS, DOCUMENTATION AND 
BROWSING FOR ANY EDITOR I 
NEW FEATURES INCLUDE: 

* Quick March of all symbol definitions and usages, even 
Inherited class members, macro expansions, etc. 

* Windows Interface source code browser with class 
hierarchy charts and function call tree diagrams 

* Browsers link to any text-mode or Windows editor. 

* Print symbol cross reference, module summaries, function 
call frees, class hierarchy charts and more. 

* Database export to QuIckHelp. ASCII CSV (dBase). 

* API library lets you directly occess the symbol database 


from your own C or C++ code! 

* PIUS ALL the classic CC-RIDER features to tackle those BIG 


unexplored programs 1 

FULLY SUPPORTS CUSS NESTING, TEMPLATES, EXCEPTIONS, 

BORLAND C++, ZORTECH C++, MS C^C+* 7 A ALL ANSI C COMPILERS 

WESTERN 

WARES 

> 

For DOS, Windows and OS/2 ) 

(303) 327-4898 

Box C Norwood, CO 81423 

( FREE DEMO DISK 'N 

1 MONEY-BACK GUARANTEE j 
_/ 
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MULTI-PLATFORM CD ROMS 


GRAPHICS 1 CD ROM $24.95 

HUNDREDS of Graphic programs & Utilities w/ source 
& sample data. Animation, drawing & Paint, converters, 
fractals, JPEG, mapping, plotting, ray tracing, etc. Full 
description of all popular graphic file formats. 16,000 
FILES, 426 MB 

AUDIO 1 CD ROM $24.95 

More than 1400 sample sounds & MOD files PLUS 
Hundreds of audio programs and utilities w/ source. 
Converters, editors, generators, players, samplers, 
speech, trackers, etc. 

LANGUAGE / OS CD ROM $39.95 
The LARGEST collection of source & executables for 
compilers, interpreters, function libraries, and 
documentations for standard and research computer 
languages and operating systems ever assembled, > 649 
MB. Includes Ada, Basic, C, C++, E, E++, Forth, Lisp, 
Mach, Modula, Oberon, Pascal, Prolog, Rexx, Scheme, 
Simula, TCL, etc. 

KNOWLEDGE MEDIA Inc. 

434 Nunneky, Suite B, Paradise, CA 9S%9 USA 
1-800-78 CD ROM - VISA/MC/COD 
+1-916-872-3826 Volce/FAX 


□ Request 168 on Reader Service Card □ 
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Network Toolkit 


This kit provides an abstract programming layer 
for developing network applications that are 
independent of the underlying network protocol. 
Developers write one application that will run 
over NetBIOS. IPX or Windows Sockets 
transparently without having to master the API 
set for each of the protocols. All network services 
are cvenL-driven with both connection-oriented 
and connectionless circuits supported. US$495. 

Interfaces: 

Visual Basic™ custom control (VBX) 
Microsoft® or Borland® C/C++ 

Borland Pascal 

Intclec Systems 

10201 W. Markham, Ste. 101 
Little Rock, Arkansas 72205 
Fax 501.221.7412 
501.221.3600 

□ Request 188 on Reader Service Card □ 
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I Does your company 
provide tools, products, 
or services for advanced 
Windows programmers? 
Then reach over 22,000 
serious programmers in: 

Windows/DOS 

□ DEVELOPER'S JOURNAL 

Call 913-841-1631 today for 
information about 
advertising opportunities in 

Windows/DOS Developer’s Journal. 

Advanced. Serious. 

Technical. 


1 Brian 

Osborn - 

Continental Europe. 

1+49 431-396895 



1 Ed - East 

1 Donna 

- Midwest 

1 Edwin - West 

1913-841-1622 

■ 913-841-6733 

1913-841-1626 


VB/ISAM™ 

CB/ISAM™ 


FAST, CLEAN, AND EASY 
serious data management 
for Visual Basic ” and C, 
both Windows" 1 and DOS. 

For professional applications since 8/91: 
VARIABLE-LENGTH fields and multi-format 
records to 64K, SUPER-FAST and reliable 
with files to 512 MB. Automatically 
maintains up to 80 indexes; small, friendfy 
API, 50KB DLL. Special offer: multi-user 
$169.95, single-user $99.95. No royalties. 

^o^ltware^Source^ 

42808 Christy Street, Ste. 222 
Fremont, California 94538 
Tel. (510) 623-7854 • Fax (510) 651-6039 


October 1993 


Phone Sound: Simple! 

For Windows/DOS Voice Mail & Fax Developers 


Professional 
Tools for 
your Voice 
Mail, Fax & 
Audiotex 
Applications 


1. Create fantastic prompts Multimedia Wave (16, 8 & 

and save time with MS ADPCM), linear 16 & 

VFEdit ®! Record, crop, cut, unsigned 8, plus Dialogic 4 
copy, paste, mix, fade, echo, & 8 at any sample rate 1 
volume & more with your 4. Scribe Transcription 
Dialogic™ D4x/12x boards u,My for DOS plays digital 

2. Add Voice Mail power to audio files in the background 

your MS Windows apps with without voice mail hardware! 
TI/F DLL ™ our Tel 1/F 5. A dd Text-to-Speech 

Dynamic Link Library capability to your apps with 

3. Audio Tool Box ™ Vox Fonts ™, our "software 

converts to and from _ only" text-to-speech library 1 


Order Now: 1-800-234-VISI 


I Voice Information Systems: 24 N Mcnon Avc, Brvn Mawr, Pa 19010 I 

Tel 215-747-5035/BBS 2 15-747-5062/ Fax j-800-234-FXlT 
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SDLC, BSC, HDLC, 
X.25 ON THE PC 

Use the Sangoma SDLA card to 
provide link support for your product 
that is cost effective, full featured, rock 
solid and easy to use. 

• Line speed to 180kbps 

• Operating statistics and built in 
datascope make your product easy 
to configure and debug 

• Menu driven test program included 

• Primary and secondary SDLC with 
multiple addresses 

• HDLC LAPB, LAPD, NRM mode 

• CCITT 1988 X.25 implrementation 

• High level interfaces under DOS, 
Unix, Windows, OS/2 

SANGOMA Technologies Inc. 

Tel: (416) 474-1990; (800) 388-2475 
FAX: (416) 474-9223 



NETWORK 

CONTROL 

LIBRARIES 

NETBIOS ROUTINES allows ac¬ 
cess to low-level network func¬ 
tions. Name, session, and 
datagram routines. Wait and no¬ 
wait options. $99 

NETBIOS DLL for Windows $199 

NETWORK MASTER provides 
access to Netware internal func¬ 
tions. Complete network control 
from your compiled programs! $99 

Starlight Software 

P.O. Box 1090 

Wheeling, IL 60090 

(708) 394-0622 _ 
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C and C++ DOCUMENTATION 


! AUTOMATED DOCUMENTATION ! 

• C-CALL ($69) Graphic-tree of caller/called 
functions, cross-ref, file/function index. 

• C-CMT ($69) Creates/inserts/updates 
comment-blocks for each function, listing 
the functions and identifiers used by it. 

• C-METRIC ($59) Counts path complexity, 
counts comments, code, ’C statements. 

• C-LIST ($69) Lists and action-diagrams, 
or reformats into standard formats. 

• C-REF ($59) Creates cross-reference of 
local/global/define/parameter identifiers. 

• ?PEC| A L : C-DOC ($199) All 5 programs 
integrated as DOS program (<15,000 lines) 

• NEW! C-DOC Professional ($299) 

DOS, OS/2, Windows. 3-ring binder/case. 
Processes 150,000 lines, deferred reports. 

• 30-DAY Money-back guarantee CALL NOW 

SOFTWARE BLACKSMITHS INC. 

6064 St Ives Way, Mississauga 

ONT, Canada Voice/Fax (416)-858-4466 

L5N-4M1 _Demos/BBS |41b|-8og-1916 


see AD INDEX for our larger ad 
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NOW IN EUROPE 


FOR ALL EUROPEAN SOFTWARE VENDORS 

In order to serve our European advertising 
customers better, Windows/DOS Developer’s 
Journal now has a European Advertising 
Representative located in Germany. 

Now it is even easier for you to reach over 
22,000 experienced Windows programmers 
worldwide with an advertisement in 
Windows/DOS Developer's Journal. (U.K. 
customers: please call Ed at 

01-913-841-1622.) 

Windows/DOS 

□ DEVELOPER'S JOURNAL 

Brian Osborn 
Hohenleuchte 10 A 
D-24159 Kiel 
Germany 

Phone: +49 431 396895 
FAX: +49 431 396827 


Wouldn’t it be nice to make your 
product known around the world? 



EXAminATQR 

Simulation of the Microsoft Windows™ Certified Professional Examinations 


Enhance your value to clients, peers and employers 
using Examinator, an interactive Windows 3.1 pro¬ 
gram that helps you prepare for and pass the Micro¬ 
soft Windows certification exams given at authorized 
testing centers worldwide. 

• Four complete simulated exams 

• Exam registration instructions and study outlines 

Benefits of this credential include a license to use 
the Microsoft Windows logo, a wall certificate, 
membership card, MCP directory listing and more! 
®89 + S&h To order, call (615) 327-1858 
VISA/ MC/Check/ MO/CDD fax (615) 320-6594 
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Dept. D Corporation 

242 Louise Ave. 

Nashville. TN 37203 
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Client/Server 
Database Solutions 


It’s available now—ready to per¬ 
form on your desktop. A new 
function-rich, 32-bit relational 
database you can really trust 
with your growing client/server 
network, your mission-critical 
data and your business. 

Introducing IBM DATABASE 2™ OS/2® 
(DB2/2™) from IBM Programming Systems, the 
birthplace of relational database technology. 

DB2/2 includes an industrial-strength DB 
engine that supports transaction management, 
concurrency control, security, integrity, and 
recovery functions. Designed to exploit the 
power and open architecture of OS/2, it also 
supports industry-standard SQL for developing 
portable applications. And it runs your DOS, 
DOS Windows™ and OS/2 
applications requiring 
online access. 

You can access data 
directly from DB2/2 on 
your desktop or from a 
DB2/2 server on your 
LAN, and with 




DISTRIBUTED DATABASE 
CONNECTION SERVICES/2™ 
from DB2: SQL/DS™ and OS/400® 
databases as if they were on your desktop, too. 
This versatility can play a significant role in 
an Information Warehouse™ solution 
for your business. 

We’ve developed an 




exciting demo diskette to show 
you just how well new DB2/2 
performs—right on your desktop. Call us today 
for your free demo, or to order DB2/2: 

1 800 342-6672; or fax: 1 800 445-2426. 

In Canada, call 1 800 465-7999, ext. 850. 

An upgrade from OS/2 Extended Edition 
or Extended Services is also available. 






IBM, OS/2, DB2 and OS/400 are registered trademarks and DATABASE 2, DB2/2, DISTRIBUTED DATABASE CONNECTION SERVICES/2, 
SQL/DS and Information Warehouse are trademarks of International Business Machines Corporation. Windows is a trademark of 
Microsoft Corporation: © 1993 IBM Corp. 







AVOID EMBARRASSMENT! 



“A customer found a bug in 
our software with a tool ~ 
called BOUNDS-CHECKER . . 

Why aren't we using 

BOUNDS-CHECKER?” 




Use BOUNDS-CHECKER™ V2.0 For Windows , The Automatic Bug Finder! 

Whether you're the boss, the QA Manager or the programmer, it's your responsibility to ensure that 
your company's Windows programs are "bug-free" before they get into the hands of customers. 
If you're developing under C or C++, producing a "bug-free" Windows product is no longer a long 
and stressful experience. 


Announcing BOUNDS-CHECKER V2.0 For 
Windows, the software developer's "safety-net". 
Quickly and easily eliminate the hardest-to-find 
Windows errors that can take days - even weeks 
to find like: 


• API Parameter Errors 

• API Return Value Errors 

• Data and Heap Corruption 

• Resource Leakage Problems 

• Memory Leakage Problems 

• Processor Faults 

BOUNDS-CHECKER works by transparently set¬ 
ting hundreds of breakpoints within your program 
to monitor its behavior. When a bug is detected, 
BOUNDS-CHECKER immediately stops your pro¬ 
gram and pops up showing the problem. You 
can then inspect your program's source, vari¬ 
ables, stack and heap... with BOUNDS-CHECKER's 
powerful display windows. 

For those particularly nasty problems, we've intro¬ 
duced new event logging. This lets you look back in time 
to see what led up to the problem. The events which 
include messages and API calls can be easily filtered with 
the click of a button so you can view only the events of 
interest. 

Unlike other debugging tools, there's no learning 
curve with BOUNDS-CHECKER. Simply select your 
program's name from BOUNDS-CHECKER's menu; all the 
rest is automatic. There is nothing to link-in and no macros 
to compile into your program. All this plus the functionality 
of a heap checker, debug kernel, API debugger, and a 
post mortem tool into a single comprehensive automatic 
bug finder. 



ANIMATE3 Registers Info 
Dgroup (seg 2) 


BOUNDS-CHECKER Trapping a Parameter Validation Error 
New For Version 2.0 

BOUNDS-CHECKER now logs all Windows events. Many 
Windows bugs are difficult to find because of the event driven, 
multi-tasking, message based nature of Windows. BOUNDS- 
CHECKER V2.0 For Windows introduces an event logging and 
display capability that captures all Windows messages, API calls, 
API returns and other events. The information is displayed in a 
high-level overview that lets you see how your program is inter¬ 
acting with Windows. When you want to see more detail, simply 
click to see a section expanded in great detail. 

Call now for overnight delivery. 

BOUNDS-CHECKER V2.0 For Windows... Only $249 
BOUNDS-CHECKER For MS DOS... $199 
Order both versions & SAVE $150... Only $298 


BOUNDS CHECKER, SOFT-ICE. AND NU-MEGA TECHNOLOGIES are trademarks owned by Nu-Mega Technologies, Inc. All other trademarks are owned by their respective owners. 
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